environment

The environment domain has 15 actions. On the meta surface they are all reached through arcane_environment; 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
`environment.create`	Create an environment	write
`environment.delete`	Delete an environment	destructive
`environment.deployment_snippets`	Get deployment snippets	read
`environment.edge_mtls_ca_download`	Download Arcane-generated edge mTLS CA	read
`environment.get`	Get an environment	read
`environment.heartbeat`	Update environment heartbeat	write
`environment.list`	List environments	read
`environment.mtls_bundle_download`	Download environment mTLS bundle	read
`environment.mtls_file_download`	Download environment mTLS asset	read
`environment.pair`	Pair agent with manager	write
`environment.pair_agent`	Pair with local agent	destructive
`environment.sync`	Sync environment	write
`environment.test`	Test environment connection	write
`environment.update`	Update an environment	destructive
`environment.version`	Get environment version	read

Actions

`environment.create`

Create an environment

Create a new Docker environment

Kind: write
Required parameters: apiUrl
Meta tool: arcane_environment with "action": "create"
Individual tool: arcane_environment_create
Arcane route: POST /api/environments
Operation ID: createEnvironment
Usage: Registers a new environment (needs environments:create). apiUrl is required (the agent’s URL, e.g. http://host:3553, or a placeholder such as edge://name with isEdge=true for an edge agent that dials in). Pass useApiKey=true to have Arcane generate the agent’s key: the environment starts as pending and the result’s apiKey (arc_…) is shown only in this answer and doubles as the agent’s AGENT_TOKEN. Otherwise pass the accessToken of an already running agent, which also pushes registries, S3 destinations and git repositories to it. Next, environment.deployment_snippets gives the docker run/compose commands to start the agent, then environment.test checks the connection.
Related actions: environment.deployment_snippets, environment.test, environment.update, environment.pair

`environment.delete`

Delete an environment

Delete a Arcane environment

Kind: destructive — requires confirm: true
Required parameters: environmentId
Meta tool: arcane_environment with "action": "delete"
Individual tool: arcane_environment_delete
Arcane route: DELETE /api/environments/{id}
Operation ID: deleteEnvironment
Usage: Removes an environment from Arcane by environmentId (from environment.list, required, needs environments:delete). It also deletes the GitOps syncs targeting that environment (their projects stay but are no longer GitOps-managed), and the remote host, its agent and its containers are not touched. The local environment “0” cannot be deleted (400).
Related actions: environment.list, environment.update, gitops.list

`environment.deployment_snippets`

Get deployment snippets

Get Docker run and compose snippets for environment deployment

Kind: read
Required parameters: none
Meta tool: arcane_environment with "action": "deployment_snippets"
Individual tool: arcane_environment_deployment_snippets
Arcane route: GET /api/environments/{id}/deployment
Operation ID: getDeploymentSnippets
Usage: Returns ready-to-run dockerRun and dockerCompose snippets that start the agent for an environment (environmentId defaults to the configured environment, needs environments:pair). They embed the environment’s access token as AGENT_TOKEN, so treat them as secret. Works only for environments holding an Arcane-generated key, i.e. created with useApiKey=true or re-keyed with environment.update regenerateApiKey=true (otherwise 400). For edge environments when the manager runs with edge mTLS enabled, mtls adds snippets and the PEM files to mount (private keys only via downloadUrl, i.e. environment.mtls_file_download or environment.mtls_bundle_download).
Related actions: environment.create, environment.mtls_bundle_download, environment.mtls_file_download, environment.test

`environment.edge_mtls_ca_download`

Download Arcane-generated edge mTLS CA

Download the Arcane-managed certificate authority used for generated edge mTLS client certificates

Kind: read
Required parameters: none
Meta tool: arcane_environment with "action": "edge_mtls_ca_download"
Individual tool: arcane_environment_edge_mtls_ca_download
Arcane route: GET /api/edge-mtls/ca
Operation ID: downloadEdgeMTLSCA
Usage: Downloads the manager-wide CA certificate Arcane uses to sign edge agents’ mTLS client certificates, as PEM text in content (the file named by EDGE_MTLS_CA_FILE when that is set). It takes no environment. Needs environments:pair, and answers 404 “not available” when edge mTLS is disabled (EDGE_MTLS_MODE unset) or the CA file does not exist. Use it where the edge tunnel’s client certificates must be verified, such as a TLS terminator in front of Arcane. Per-environment client certificates come from environment.mtls_bundle_download.
Related actions: environment.mtls_bundle_download, environment.mtls_file_download

`environment.get`

Get an environment

Get a Docker environment by ID

Kind: read
Required parameters: environmentId
Meta tool: arcane_environment with "action": "get"
Individual tool: arcane_environment_get
Arcane route: GET /api/environments/{id}
Operation ID: getEnvironment
Usage: Full record of one environment by environmentId (from environment.list, required here, no default): status, enabled, apiUrl, connected, lastSeen/lastHeartbeat, edge transport and session details, and for edge environments with Arcane-generated mTLS the client certificate’s expiry (edgeMTLSCertificate). Needs environments:read, and an unknown ID gives 404. For a direct environment status is the last recorded one (run environment.test to refresh it). For an edge environment status and connected reflect the live tunnel (online while connected, standby when only polling, otherwise offline).
Related actions: environment.list, environment.test, environment.version, environment.update

`environment.heartbeat`

Update environment heartbeat

Update the heartbeat timestamp for an environment

Kind: write
Required parameters: none
Meta tool: arcane_environment with "action": "heartbeat"
Individual tool: arcane_environment_heartbeat
Arcane route: POST /api/environments/{id}/heartbeat
Operation ID: updateHeartbeat
Usage: Marks the environment online with lastSeen set to now (environmentId defaults to the configured environment, needs environments:sync), without contacting the agent. Writes are throttled to one every 30 seconds while already online. It also lifts a pending direct environment to online without pairing (a pending edge environment stays pending until its agent pairs), and an unknown environmentId fails with 404. Meant for agents reporting liveness: to really check a host use environment.test.
Related actions: environment.test, environment.get

`environment.list`

List environments

Get a paginated list of Docker environments

Kind: read
Required parameters: none
Meta tool: arcane_environment with "action": "list"
Individual tool: arcane_environment_list
Arcane route: GET /api/environments
Operation ID: listEnvironments
Usage: Lists the Docker hosts (environments) Arcane manages, each with id, name, apiUrl, status (online, offline, pending, standby, error), enabled, isEdge and live edge connection fields. The id is the environmentId every other action takes (“0” is Arcane’s local Docker host). Any logged-in caller may list, but only the environments they hold a permission on are returned. Filter with search (name or apiUrl) and type (comma-separated: http for direct agents and the local host, websocket or grpc for edge agents by the transport they use or last used, polling for edge agents that have polled, edge for the other edge agents). Paginate with start and limit (default 20).
Related actions: environment.get, environment.test, environment.create, dashboard.get

`environment.mtls_bundle_download`

Download environment mTLS bundle

Download the generated mTLS client certificate bundle for an edge environment

Kind: read
Required parameters: none
Meta tool: arcane_environment with "action": "mtls_bundle_download"
Individual tool: arcane_environment_mtls_bundle_download
Arcane route: GET /api/environments/{id}/deployment/mtls/bundle
Operation ID: downloadEnvironmentMTLSBundle
Usage: Downloads all Arcane-generated mTLS files of an edge environment (CA certificate, agent certificate and agent private key) as one zip, returned as a binary attachment (environmentId defaults to the configured environment, needs environments:pair). Fails with 400 for a non-edge environment or one without a generated key, and 404 “not available” when the manager does not run with EDGE_MTLS_MODE optional or required or signs with its own EDGE_MTLS_CA_FILE instead of the generated CA. Each download is recorded as an audit event.
Related actions: environment.deployment_snippets, environment.mtls_file_download, environment.edge_mtls_ca_download

`environment.mtls_file_download`

Download environment mTLS asset

Download an individual generated mTLS client certificate asset for an edge environment

Kind: read
Required parameters: fileName
Meta tool: arcane_environment with "action": "mtls_file_download"
Individual tool: arcane_environment_mtls_file_download
Arcane route: GET /api/environments/{id}/deployment/mtls/{fileName}
Operation ID: downloadEnvironmentMTLSFile
Usage: Downloads one Arcane-generated mTLS file of an edge environment as PEM text in content. fileName is a name from environment.deployment_snippets mtls.files (ca.crt, agent.crt or agent.key), and this is the only way besides the bundle to obtain the private key agent.key. Needs environments:pair, with the same preconditions and 404 “not available” without edge mTLS as environment.mtls_bundle_download, and each download is audited.
Related actions: environment.deployment_snippets, environment.mtls_bundle_download

`environment.pair`

Pair agent with manager

Agent sends API key to complete environment pairing

Kind: write
Required parameters: none
Meta tool: arcane_environment with "action": "pair"
Individual tool: arcane_environment_pair
Arcane route: POST /api/environments/pair
Operation ID: pairEnvironment
Usage: Completes pairing the way an agent does on first start, so it is normally not needed: apiKey is the arc_ key returned by environment.create with useApiKey=true (or by environment.update with regenerateApiKey=true) and is the only credential sent. The environment must still be pending (otherwise 400). Pairing moves it out of pending and pushes registries, S3 destinations and git repositories to it. A wrong key gives 401.
Related actions: environment.create, environment.get, environment.deployment_snippets

`environment.pair_agent`

Pair with local agent

Generate or rotate the local agent pairing token

Kind: destructive — only when rotate is true; those calls require confirm: true, the others do not
Required parameters: none
Meta tool: arcane_environment with "action": "pair_agent"
Individual tool: arcane_environment_pair_agent
Arcane route: POST /api/environments/{id}/agent/pair
Operation ID: pairAgent
Usage: Returns this Arcane instance’s own agent token (token), used when this instance is to be managed as an agent by another Arcane manager. It works only for the local environment “0”, which is also its default here whatever ARCANE_ENVIRONMENT_ID says (any other ID gives 404), and needs environments:pair. Without rotate it returns the existing token (creating one if none exists). rotate=true replaces it, so a manager using the old token loses access, and only that needs confirm=true.
Related actions: environment.create, environment.update

`environment.sync`

Sync environment

Sync container registries, S3 destinations, and git repositories to a remote environment. Returns an error if any resource group fails. Other groups may still sync successfully.

Kind: write
Required parameters: none
Meta tool: arcane_environment with "action": "sync"
Individual tool: arcane_environment_sync
Arcane route: POST /api/environments/{id}/sync
Operation ID: syncEnvironment
Usage: Pushes the manager’s container registries, S3 destinations and git repositories to a remote environment now (environmentId defaults to the configured environment, needs environments:sync), the same push Arcane starts in the background after pairing, after creating an environment with an accessToken, or after environment.update sends accessToken or name. Runs to completion as an activity and returns its activityId (follow with activity.get). If any group fails the call errors, though the other groups may have synced. Fails for the local environment “0”, which has nothing to push to.
Related actions: activity.get, registry.list, s3_destination.list, git_repository.list

`environment.test`

Test environment connection

Test connectivity to a Arcane environment

Kind: write
Required parameters: none
Meta tool: arcane_environment with "action": "test"
Individual tool: arcane_environment_test
Arcane route: POST /api/environments/{id}/test
Operation ID: testConnection
Usage: Probes the environment now (environmentId defaults to the configured environment, needs environments:read): GET /api/health on a direct agent, through the tunnel for an edge agent, a Docker ping for the local environment “0”. It returns status (online when reachable), and an unreachable agent is reported as an error. Without apiUrl the result is saved as the environment’s status and lastSeen, which also promotes a pending direct environment to online. Pass apiUrl (needs environments:update) to try a different URL without saving anything before calling environment.update.
Related actions: environment.get, environment.update, environment.version

`environment.update`

Update an environment

Update a Docker environment

Kind: destructive — only when regenerateApiKey is true; those calls require confirm: true, the others do not
Required parameters: environmentId
Meta tool: arcane_environment with "action": "update"
Individual tool: arcane_environment_update
Arcane route: PUT /api/environments/{id}
Operation ID: updateEnvironment
Usage: Changes an environment by environmentId (from environment.list, required, needs environments:update). Only supplied fields change. Changing apiUrl while an access token is stored fails unless accessToken is sent again in the same call. For the local environment “0” only name can change. regenerateApiKey=true issues a new key (returned once in apiKey), invalidates the old one and resets the environment to pending, so the agent must be redeployed with the new token (see environment.deployment_snippets), and only that needs confirm=true. enabled=false stops health checks, and an enabled environment is re-tested in the background after the update.
Related actions: environment.get, environment.test, environment.deployment_snippets, environment.sync

`environment.version`

Get environment version

Get the version of a remote environment

Kind: read
Required parameters: none
Meta tool: arcane_environment with "action": "version"
Individual tool: arcane_environment_version
Arcane route: GET /api/environments/{id}/version
Operation ID: getEnvironmentVersion
Usage: Version of the Arcane build running in an environment (environmentId defaults to the configured environment, needs environments:read): currentVersion, revision, goVersion, enabledFeatures, and update fields such as updateAvailable and newestVersion. For a remote environment it asks the agent (15-second timeout) and a success also records a heartbeat (marks it online). For the manager itself server.app_version is equivalent.
Related actions: environment.test, environment.get, server.app_version