environment

El dominio environment tiene 15 acciones. En la superficie meta se alcanzan todas a través de arcane_environment; en la individual, cada una es una herramienta propia; en la dinámica se ejecutan con arcane_execute_action y el ID canónico.

Resumen

Acción	Título	Tipo
environment.create	Create an environment	escritura
environment.delete	Delete an environment	destructiva
environment.deployment_snippets	Get deployment snippets	lectura
environment.edge_mtls_ca_download	Download Arcane-generated edge mTLS CA	lectura
environment.get	Get an environment	lectura
environment.heartbeat	Update environment heartbeat	escritura
environment.list	List environments	lectura
environment.mtls_bundle_download	Download environment mTLS bundle	lectura
environment.mtls_file_download	Download environment mTLS asset	lectura
environment.pair	Pair agent with manager	escritura
environment.pair_agent	Pair with local agent	destructiva
environment.sync	Sync environment	escritura
environment.test	Test environment connection	escritura
environment.update	Update an environment	destructiva
environment.version	Get environment version	lectura

Acciones

environment.create

Create an environment

Create a new Docker environment

• Tipo: escritura
• Parámetros obligatorios: apiUrl
• Meta-herramienta: arcane_environment con "action": "create"
• Herramienta individual: arcane_environment_create
• Ruta de Arcane: POST /api/environments
• ID de operación: createEnvironment
• Uso: 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.
• Acciones relacionadas: environment.deployment_snippets, environment.test, environment.update, environment.pair

environment.delete

Delete an environment

Delete a Arcane environment

• Tipo: destructiva — exige confirm: true
• Parámetros obligatorios: environmentId
• Meta-herramienta: arcane_environment con "action": "delete"
• Herramienta individual: arcane_environment_delete
• Ruta de Arcane: DELETE /api/environments/{id}
• ID de operación: deleteEnvironment
• Uso: 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).
• Acciones relacionadas: environment.list, environment.update, gitops.list

environment.deployment_snippets

Get deployment snippets

Get Docker run and compose snippets for environment deployment

• Tipo: lectura
• Parámetros obligatorios: ninguno
• Meta-herramienta: arcane_environment con "action": "deployment_snippets"
• Herramienta individual: arcane_environment_deployment_snippets
• Ruta de Arcane: GET /api/environments/{id}/deployment
• ID de operación: getDeploymentSnippets
• Uso: 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).
• Acciones relacionadas: 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

• Tipo: lectura
• Parámetros obligatorios: ninguno
• Meta-herramienta: arcane_environment con "action": "edge_mtls_ca_download"
• Herramienta individual: arcane_environment_edge_mtls_ca_download
• Ruta de Arcane: GET /api/edge-mtls/ca
• ID de operación: downloadEdgeMTLSCA
• Uso: 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.
• Acciones relacionadas: environment.mtls_bundle_download, environment.mtls_file_download

environment.get

Get an environment

Get a Docker environment by ID

• Tipo: lectura
• Parámetros obligatorios: environmentId
• Meta-herramienta: arcane_environment con "action": "get"
• Herramienta individual: arcane_environment_get
• Ruta de Arcane: GET /api/environments/{id}
• ID de operación: getEnvironment
• Uso: 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).
• Acciones relacionadas: environment.list, environment.test, environment.version, environment.update

environment.heartbeat

Update environment heartbeat

Update the heartbeat timestamp for an environment

• Tipo: escritura
• Parámetros obligatorios: ninguno
• Meta-herramienta: arcane_environment con "action": "heartbeat"
• Herramienta individual: arcane_environment_heartbeat
• Ruta de Arcane: POST /api/environments/{id}/heartbeat
• ID de operación: updateHeartbeat
• Uso: 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.
• Acciones relacionadas: environment.test, environment.get

environment.list

List environments

Get a paginated list of Docker environments

• Tipo: lectura
• Parámetros obligatorios: ninguno
• Meta-herramienta: arcane_environment con "action": "list"
• Herramienta individual: arcane_environment_list
• Ruta de Arcane: GET /api/environments
• ID de operación: listEnvironments
• Uso: 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).
• Acciones relacionadas: 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

• Tipo: lectura
• Parámetros obligatorios: ninguno
• Meta-herramienta: arcane_environment con "action": "mtls_bundle_download"
• Herramienta individual: arcane_environment_mtls_bundle_download
• Ruta de Arcane: GET /api/environments/{id}/deployment/mtls/bundle
• ID de operación: downloadEnvironmentMTLSBundle
• Uso: 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.
• Acciones relacionadas: 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

• Tipo: lectura
• Parámetros obligatorios: fileName
• Meta-herramienta: arcane_environment con "action": "mtls_file_download"
• Herramienta individual: arcane_environment_mtls_file_download
• Ruta de Arcane: GET /api/environments/{id}/deployment/mtls/{fileName}
• ID de operación: downloadEnvironmentMTLSFile
• Uso: 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.
• Acciones relacionadas: environment.deployment_snippets, environment.mtls_bundle_download

environment.pair

Pair agent with manager

Agent sends API key to complete environment pairing

• Tipo: escritura
• Parámetros obligatorios: ninguno
• Meta-herramienta: arcane_environment con "action": "pair"
• Herramienta individual: arcane_environment_pair
• Ruta de Arcane: POST /api/environments/pair
• ID de operación: pairEnvironment
• Uso: 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.
• Acciones relacionadas: environment.create, environment.get, environment.deployment_snippets

environment.pair_agent

Pair with local agent

Generate or rotate the local agent pairing token

• Tipo: destructiva — solo cuando rotate is true; esas llamadas exigen confirm: true, las demás no
• Parámetros obligatorios: ninguno
• Meta-herramienta: arcane_environment con "action": "pair_agent"
• Herramienta individual: arcane_environment_pair_agent
• Ruta de Arcane: POST /api/environments/{id}/agent/pair
• ID de operación: pairAgent
• Uso: 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.
• Acciones relacionadas: 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.

• Tipo: escritura
• Parámetros obligatorios: ninguno
• Meta-herramienta: arcane_environment con "action": "sync"
• Herramienta individual: arcane_environment_sync
• Ruta de Arcane: POST /api/environments/{id}/sync
• ID de operación: syncEnvironment
• Uso: 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.
• Acciones relacionadas: activity.get, registry.list, s3_destination.list, git_repository.list

environment.test

Test environment connection

Test connectivity to a Arcane environment

• Tipo: escritura
• Parámetros obligatorios: ninguno
• Meta-herramienta: arcane_environment con "action": "test"
• Herramienta individual: arcane_environment_test
• Ruta de Arcane: POST /api/environments/{id}/test
• ID de operación: testConnection
• Uso: 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.
• Acciones relacionadas: environment.get, environment.update, environment.version

environment.update

Update an environment

Update a Docker environment

• Tipo: destructiva — solo cuando regenerateApiKey is true; esas llamadas exigen confirm: true, las demás no
• Parámetros obligatorios: environmentId
• Meta-herramienta: arcane_environment con "action": "update"
• Herramienta individual: arcane_environment_update
• Ruta de Arcane: PUT /api/environments/{id}
• ID de operación: updateEnvironment
• Uso: 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.
• Acciones relacionadas: environment.get, environment.test, environment.deployment_snippets, environment.sync

environment.version

Get environment version

Get the version of a remote environment

• Tipo: lectura
• Parámetros obligatorios: ninguno
• Meta-herramienta: arcane_environment con "action": "version"
• Herramienta individual: arcane_environment_version
• Ruta de Arcane: GET /api/environments/{id}/version
• ID de operación: getEnvironmentVersion
• Uso: 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.
• Acciones relacionadas: environment.test, environment.get, server.app_version