project

The project domain has 26 actions. On the meta surface they are all reached through arcane_project; on the individual surface each one is its own tool; on the dynamic surface run them with arcane_execute_action and the canonical ID.

Summary

Action	Title	Kind
project.archive	Archive a project	write
project.build	Build project images	write
project.compose	Get project compose details	read
project.counts	Get project status counts	read
project.create	Create a project	write
project.destroy	Destroy a project	destructive
project.down	Bring down a project	destructive
project.get	Get a project	read
project.list	List projects	read
project.logs	Get project logs	read
project.pull	Pull project images	write
project.redeploy	Redeploy a project	destructive
project.references	List project references	read
project.restart	Restart a project	write
project.runtime	Get project runtime	read
project.tags	List project tags	read
project.tags_update	Update a project tag	write
project.unarchive	Unarchive a project	write
project.up	Deploy a project	destructive
project.update	Update a project	destructive
project.update_services	Update project services	destructive
project.updates	Get project updates	read
project.workspace_file_download	Download project workspace file	read
project.workspace_file_get	Get project workspace file	read
project.workspace_get	Get project workspace	read
project.workspace_update	Update project workspace	destructive

Actions

project.archive

Archive a project

Archive a stopped Docker Compose project

• Kind: write
• Required parameters: projectId
• Meta tool: arcane_project with "action": "archive"
• Individual tool: arcane_project_archive
• Arcane route: POST /api/environments/{id}/projects/{projectId}/archive
• Operation ID: archive-project
• Usage: Marks a stopped project as archived: hidden from project.list unless archived=true or all, and up, down, restart, pull, build, update and workspace changes are refused until project.unarchive. Fails while any service is running, so run project.down first. Files, volumes and the record are kept.
• Related actions: project.down, project.unarchive, project.list

project.build

Build project images

Build Docker Compose services with build directives using BuildKit

• Kind: write
• Required parameters: projectId
• Meta tool: arcane_project with "action": "build"
• Individual tool: arcane_project_build
• Arcane route: POST /api/environments/{id}/projects/{projectId}/build
• Operation ID: build-project-images
• Usage: Builds the images of services with a build directive (project.get reports hasBuildDirective) from the project workspace with BuildKit, waiting for completion. services limits it to named services. load=true loads the result into the local Docker image store, push=true pushes it, provider overrides the build provider. It does not start containers: follow with project.up.
• Related actions: project.get, project.workspace_update, project.up, image.list

project.compose

Get project compose details

Get compose content, includes, and service configs for a project

• Kind: read
• Required parameters: projectId
• Meta tool: arcane_project with "action": "compose"
• Individual tool: arcane_project_compose
• Arcane route: GET /api/environments/{id}/projects/{projectId}/compose
• Operation ID: get-project-compose
• Usage: Returns composeContent, envContent, overrideContent with overrideFileName, the selected composeFiles, include files and the parsed service configs. Read it before project.update, which replaces those contents.
• Related actions: project.update, project.get, project.workspace_get

project.counts

Get project status counts

Get counts of running, stopped, and total projects

• Kind: read
• Required parameters: none
• Meta tool: arcane_project with "action": "counts"
• Individual tool: arcane_project_counts
• Arcane route: GET /api/environments/{id}/projects/counts
• Operation ID: get-project-status-counts
• Usage: Numbers of running, stopped, archived and total projects in the environment. Use project.list with a status filter to get the projects themselves.
• Related actions: project.list

project.create

Create a project

Create a new Docker Compose project

• Kind: write
• Required parameters: manifest, project
• Meta tool: arcane_project with "action": "create"
• Individual tool: arcane_project_create
• Arcane route: POST /api/environments/{id}/projects
• Operation ID: create-project
• Usage: Creates a project directory and record in status stopped without deploying it. Deploy with project.up using the returned id. project is a JSON string {“name”,“composeContent”,“envContent”?,“tags”?,“tagColors”?} (a top-level name: in the compose content overrides name, compose content can come from template.content). manifest is a JSON string {“fileChanges”:[{“operation”:“create_file”|“create_folder”,“relativePath”:“data/x.txt”,“uploadIndex”:0}]}, with uploadIndex pointing into files, or {“fileChanges”:[]} when there are no extra files.
• Related actions: project.up, project.get, template.content, gitops.create

project.destroy

Destroy a project

Bring a Docker Compose project down and delete it. removeFiles defaults to true (deletes the project directory) and removeVolumes also deletes its volumes

• Kind: destructive — requires confirm: true
• Required parameters: projectId
• Meta tool: arcane_project with "action": "destroy"
• Individual tool: arcane_project_destroy
• Arcane route: DELETE /api/environments/{id}/projects/{projectId}/destroy
• Operation ID: destroy-project
• Usage: Brings the project down and deletes it from Arcane. removeFiles defaults to true when omitted and deletes the project directory. removeFiles=false keeps the files and, for a project inside the projects directory, renames its directory to a hidden .arcane-trash-* folder so it is not re-imported. removeVolumes=true also deletes the project’s volumes and their data. Irreversible, use project.down to only stop it.
• Related actions: project.list, project.down, project.archive

project.down

Bring down a project

Bring down a Docker Compose project (docker-compose down)

• Kind: destructive — requires confirm: true
• Required parameters: projectId
• Meta tool: arcane_project with "action": "down"
• Individual tool: arcane_project_down
• Arcane route: POST /api/environments/{id}/projects/{projectId}/down
• Operation ID: down-project
• Usage: Stops and removes the project’s containers and networks (docker compose down). Volumes, files and the project record are kept, so project.up starts it again. Use project.destroy to delete the project, and run this before project.archive, which requires no running services. Fails on an archived project.
• Related actions: project.up, project.runtime, project.archive, project.destroy

project.get

Get a project

Get a Docker Compose project by ID

• Kind: read
• Required parameters: projectId
• Meta tool: arcane_project with "action": "get"
• Individual tool: arcane_project_get
• Arcane route: GET /api/environments/{id}/projects/{projectId}
• Operation ID: get-project
• Usage: Summary of one project (projectId from project.list): status, live serviceCount/runningCount, tags, path, isArchived, hasBuildDirective, GitOps origin and configurationError. It does not include the compose content or per-service state: use project.compose for the files and parsed service configs, project.runtime for each service’s container.
• Related actions: project.list, project.compose, project.runtime, project.updates

project.list

List projects

Get a paginated list of Docker Compose projects

• Kind: read
• Required parameters: none
• Meta tool: arcane_project with "action": "list"
• Individual tool: arcane_project_list
• Arcane route: GET /api/environments/{id}/projects
• Operation ID: list-projects
• Usage: Paginated projects (stacks) with id, status, serviceCount and runningCount. The id is the projectId every other project action needs. search matches name, path, status, directory and tag names. Filter with status (running,stopped,partially running), updates (has_update, up_to_date, error, unknown), tags (comma-separated, any match, names from project.tags), label, or name (exact project names, comma-separated, to resolve a known name to its projectId). Archived projects are hidden unless archived=true (only archived) or archived=all.
• Related actions: project.get, project.references, project.counts, project.tags

project.logs

Get project logs

Return the recent log lines of every service of a Docker Compose project, each tagged with its service, optionally listening for new lines for a few seconds

• Kind: read
• Required parameters: projectId
• Meta tool: arcane_project with "action": "logs"
• Individual tool: arcane_project_logs
• Arcane route: GET /api/environments/{id}/ws/projects/{projectId}/logs (WebSocket)
• Operation ID: ws-project-logs
• Usage: Interleaved logs of all the project’s containers (projectId from project.list), each line tagged with its service. It needs the projects:logs permission. tail (default 100, or all) and since bound the history, and follow=true keeps listening for seconds (default 5, max 120). For one container’s logs or a full log file use container.logs or container.logs_download.
• Related actions: project.runtime, container.logs, project.restart

project.pull

Pull project images

Pull all images for a Docker Compose project with streaming progress output

• Kind: write
• Required parameters: projectId
• Meta tool: arcane_project with "action": "pull"
• Individual tool: arcane_project_pull
• Arcane route: POST /api/environments/{id}/projects/{projectId}/pull
• Operation ID: pull-project-images
• Usage: Pulls every pullable image referenced by the project and waits for completion. Running containers keep their current images until project.up or project.redeploy recreates them. Use project.redeploy to pull and apply in one step. Fails on an archived project.
• Related actions: project.up, project.redeploy, project.updates

project.redeploy

Redeploy a project

Pull the images of a Docker Compose project and bring it up again (pull + up, no down first)

• Kind: destructive — requires confirm: true
• Required parameters: projectId
• Meta tool: arcane_project with "action": "redeploy"
• Individual tool: arcane_project_redeploy
• Arcane route: POST /api/environments/{id}/projects/{projectId}/redeploy
• Operation ID: redeploy-project
• Usage: Pulls the project’s images (a failed pull is only logged and stops the remaining pulls) and then brings it up again like project.up, recreating containers whose image or configuration changed. It does not run compose down first. Takes the same options as project.up (pullPolicy, forceRecreate, removeOrphans, recreateVolumes, build) and waits for completion. Arcane refuses to redeploy its own container.
• Related actions: project.updates, project.update_services, project.runtime, project.logs

project.references

List project references

Get the ID and name of every project, including archived projects, without runtime state

• Kind: read
• Required parameters: none
• Meta tool: arcane_project with "action": "references"
• Individual tool: arcane_project_references
• Arcane route: GET /api/environments/{id}/projects/references
• Operation ID: list-project-references
• Since: Arcane v2.15.1
• Usage: Lightweight id and name of every project, archived ones included, sorted by name and without status. Use it to resolve a project name to its projectId. Use project.list for status, filters and pagination.
• Related actions: project.list, project.get

project.restart

Restart a project

Restart the containers of a Docker Compose project, all of them or only the named services

• Kind: write
• Required parameters: projectId
• Meta tool: arcane_project with "action": "restart"
• Individual tool: arcane_project_restart
• Arcane route: POST /api/environments/{id}/projects/{projectId}/restart
• Operation ID: restart-project
• Usage: Restarts the existing containers of the project (docker compose restart) without recreating them, so compose or env changes are not applied: use project.up or project.redeploy for that. services limits it to the named services (names from project.runtime), and empty restarts all. Fails on an archived project.
• Related actions: project.runtime, project.up, project.redeploy, project.logs

project.runtime

Get project runtime

Get runtime service state for a project

• Kind: read
• Required parameters: projectId
• Meta tool: arcane_project with "action": "runtime"
• Individual tool: arcane_project_runtime
• Arcane route: GET /api/environments/{id}/projects/{projectId}/runtime
• Operation ID: get-project-runtime
• Usage: Live state of each service: runtimeServices lists name, image, status, health, ports, containerId and containerName, plus the project’s status and runningCount. Use the containerId with container.* actions and the service names with project.restart or project.update_services.
• Related actions: container.get, project.logs, project.restart, project.get

project.tags

List project tags

Get sorted, distinct project tag names

• Kind: read
• Required parameters: none
• Meta tool: arcane_project with "action": "tags"
• Individual tool: arcane_project_tags
• Arcane route: GET /api/environments/{id}/projects/tags
• Operation ID: list-project-tags
• Usage: Catalog of tag names and colors used by the environment’s projects (Arcane-managed and Compose-defined). Use the names for the tags filter of project.list or with project.tags_update.
• Related actions: project.list, project.tags_update

project.tags_update

Update a project tag

Attach or detach a UI-managed project tag

• Kind: write
• Required parameters: projectId, attached, name
• Meta tool: arcane_project with "action": "tags_update"
• Individual tool: arcane_project_tags_update
• Arcane route: PATCH /api/environments/{id}/projects/{projectId}/tags
• Operation ID: update-project-tag
• Usage: Attaches (attached=true) or detaches (attached=false) one Arcane-managed tag on a project and returns the project’s tags. color (gray, purple, blue, green, yellow, orange, red, pink) only applies to a tag name not used yet, and existing names keep their color. Tags defined in the compose file (x-arcane metadata) cannot be changed here and return a conflict.
• Related actions: project.tags, project.get, project.list

project.unarchive

Unarchive a project

Unarchive a Docker Compose project

• Kind: write
• Required parameters: projectId
• Meta tool: arcane_project with "action": "unarchive"
• Individual tool: arcane_project_unarchive
• Arcane route: POST /api/environments/{id}/projects/{projectId}/unarchive
• Operation ID: unarchive-project
• Usage: Clears the archived flag (projectId from project.list with archived=true or project.references) so the project can be deployed and edited again. It does not start it. Does nothing on a project that is not archived.
• Related actions: project.list, project.up, project.archive

project.up

Deploy a project

Deploy a Docker Compose project (docker-compose up)

• Kind: destructive — only when recreateVolumes is true or forceRecreate is true or removeOrphans is true; those calls require confirm: true, the others do not
• Required parameters: projectId
• Meta tool: arcane_project with "action": "up"
• Individual tool: arcane_project_up
• Arcane route: POST /api/environments/{id}/projects/{projectId}/up
• Operation ID: deploy-project
• Usage: Brings the project up and waits until Arcane reports completion. The result has status, activityId and the tail of the compose output. pullPolicy (missing, always, never) overrides the defaultDeployPullPolicy setting, forceRecreate recreates unchanged containers, removeOrphans removes containers of services no longer in the compose file, and recreateVolumes recreates volumes whose configuration changed, losing their data. Those three (all false by default) need confirm=true, as project.redeploy does, but a plain up does not. build=true (Arcane v2.17.2 and later, older releases answer 422) rebuilds the image of every service with a build section before deploying (otherwise its pull_policy decides, by default pulling a missing image and building only when that pull fails). A GitOps-managed project removes orphans on every deploy whatever removeOrphans says. Fails on an archived project (project.unarchive first).
• Related actions: project.runtime, project.logs, project.redeploy, project.down

project.update

Update a project

Update a Docker Compose project configuration

• Kind: destructive — requires confirm: true
• Required parameters: projectId
• Meta tool: arcane_project with "action": "update"
• Individual tool: arcane_project_update
• Arcane route: PUT /api/environments/{id}/projects/{projectId}
• Operation ID: update-project
• Usage: Replaces the compose file (composeContent), .env (envContent) or override file (overrideContent, where an empty string deletes it) with the full new text. Omitted fields are kept. name renames the project, which must be stopped, and also renames its directory and migrates its named volumes (a top-level name: in the compose content wins). Running containers are not changed: apply with project.up or project.redeploy. Returns the full project details.
• Related actions: project.compose, project.up, project.redeploy

project.update_services

Update project services

Pull latest images and recreate the given services (all services when none are specified)

• Kind: destructive — requires confirm: true
• Required parameters: projectId
• Meta tool: arcane_project with "action": "update_services"
• Individual tool: arcane_project_update_services
• Arcane route: POST /api/environments/{id}/projects/{projectId}/update-services
• Operation ID: update-project-services
• Usage: Updates selected services in place and waits for the result: when a service’s update-policy labels select a newer image tag, that tag is first written into the compose file. Then the images are pulled and the services (and services sharing their namespaces) are recreated. services lists service names (from project.runtime), and empty updates all. A service with a tag update policy makes it fail on a GitOps-managed project or a locally built service. Use project.redeploy to redeploy the whole project instead. It fails on an archived project.
• Related actions: project.updates, updater.project_check, project.runtime, project.redeploy

project.updates

Get project updates

Get image update summary for a project

• Kind: read
• Required parameters: projectId
• Meta tool: arcane_project with "action": "updates"
• Individual tool: arcane_project_updates
• Arcane route: GET /api/environments/{id}/projects/{projectId}/updates
• Operation ID: get-project-updates
• Usage: Image update summary of the project from Arcane’s stored image-update records: updateInfo has hasUpdate, imagesWithUpdates, serviceUpdates and lastCheckedAt, next to the parsed service configs. It does not contact registries. Run updater.project_check for a fresh check, then project.update_services or project.redeploy to apply.
• Related actions: updater.project_check, project.update_services, project.redeploy

project.workspace_file_download

Download project workspace file

• Kind: read
• Required parameters: projectId
• Meta tool: arcane_project with "action": "workspace_file_download"
• Individual tool: arcane_project_workspace_file_download
• Arcane route: GET /api/environments/{id}/projects/{projectId}/workspace/file/download
• Operation ID: download-project-workspace-file
• Usage: Downloads one workspace file (relativePath from project.workspace_get) as an attachment with its filename, without the size limit of project.workspace_file_get. Use it for binary or large files. Directories and the compose/.env files are rejected.
• Related actions: project.workspace_get, project.workspace_file_get

project.workspace_file_get

Get project workspace file

• Kind: read
• Required parameters: projectId
• Meta tool: arcane_project with "action": "workspace_file_get"
• Individual tool: arcane_project_workspace_file_get
• Arcane route: GET /api/environments/{id}/projects/{projectId}/workspace/file
• Operation ID: get-project-workspace-file
• Usage: Text content of one workspace file (relativePath from project.workspace_get), with editable and readOnlyReason. Binary, too_large, symlink and special files come back without content, so use project.workspace_file_download for those. Directories and the compose/.env files are rejected.
• Related actions: project.workspace_get, project.workspace_file_download, project.workspace_update

project.workspace_get

Get project workspace

• Kind: read
• Required parameters: projectId
• Meta tool: arcane_project with "action": "workspace_get"
• Individual tool: arcane_project_workspace_get
• Arcane route: GET /api/environments/{id}/projects/{projectId}/workspace
• Operation ID: get-project-workspace
• Usage: File tree of the project directory (files with relativePath, size, editable and readOnlyReason) and the fileTreeRevision that project.workspace_update requires. The compose, override and .env files are not part of the workspace: read them with project.compose. fileTreeTruncated=true means the listing stopped at Arcane’s entry limit.
• Related actions: project.workspace_file_get, project.workspace_file_download, project.workspace_update, project.compose

project.workspace_update

Update project workspace

• Kind: destructive — requires confirm: true
• Required parameters: projectId, manifest
• Meta tool: arcane_project with "action": "workspace_update"
• Individual tool: arcane_project_workspace_update
• Arcane route: PUT /api/environments/{id}/projects/{projectId}/workspace
• Operation ID: update-project-workspace
• Usage: Applies up to 500 file changes to the project directory atomically (all are rolled back if one fails). manifest is a JSON string {“fileTreeRevision”: <current value from project.workspace_get, a stale one is rejected as a conflict>, “fileChanges”:[{“operation”:“create_file”|“update_file”|“create_folder”|“rename”|“move”|“delete”,“relativePath”:…,“uploadIndex”:0}]}: uploadIndex points into files, rename takes newName, move takes newParentPath, delete of a non-empty folder needs recursive=true. The compose, override and .env files cannot be changed here (use project.update), GitOps-synced files are read-only and archived projects are rejected. Bind-mounted files change in running containers at once, but build contexts and anything read only at start-up need project.build, project.up or project.redeploy.
• Related actions: project.workspace_get, project.workspace_file_get, project.update, project.redeploy