Skip to main content

Arcane

@thomas/arcanev2026.10.11.1· 1mo agoBEHAVIORS
01README

Management of an Arcane Docker instance through its REST API: GitOps sync setup, compose project lifecycle with a validated deploy for each mode, swarm stack deploy (validated after render, polled until converged), secret/config rotation, and volume/prune cleanup.

02Behaviors1
@thomas/arcanev2026.10.11.1arcane.ts

Global Arguments

ArgumentTypeDescription
baseUrlstringArcane base URL including port, e.g. https://arcane.example.com:8443. Use https; over http the API key is sent in clear text.
apiKeystringArcane API key (X-API-Key). Supply via vault: ${{ vault.get(name, key) }}
environmentId?stringArcane environment id; 0 is the local Docker environment
skipTlsVerify?booleanAccept self-signed certs (default false: a valid cert is expected)
syncs?arrayDesired GitOps sync entries, reconciled by gitops_sync_ensure
fn version()
Read Arcane's version (GET /version); use it before and after upgrading the manager
fn gitops_repo_list()
List Arcane git repository connections (factory: one `repository` per entry, named `repository:<name>`)
fn gitops_repo_ensure()
Reconcile the git repository connection from globalArgs.repository (create or update). Secrets are sent only when present in the spec.
fn gitops_repo_delete(name: string)
Delete a git repository connection by name. Idempotent: a connection that is already gone counts as deleted.
ArgumentTypeDescription
namestringName of the git repository connection to delete
fn gitops_sync_list()
List Arcane GitOps syncs (factory: one `sync` per entry, named `sync:<name>`)
fn gitops_sync_ensure(prune?: boolean)
Reconcile GitOps syncs from globalArgs.syncs against Arcane (create missing, update drifted). With prune=true, deletes deploy syncs not in the desired list; backup syncs are left alone.
ArgumentTypeDescription
prune?booleanDelete existing deploy syncs whose name is not in globalArgs.syncs (destructive). Backup syncs are never pruned.
fn gitops_sync_trigger(names?: array)
Run the named syncs (fan-out): git pull, and a redeploy when the content changed. Empty `names` triggers every deploy sync; a backup sync runs only when named. Waits for each sync to finish; records every result, then throws if Arcane reported any sync failed or already in progress.
ArgumentTypeDescription
names?arraySync names to trigger; empty means every deploy sync (a backup sync runs only when named)
fn gitops_sync_status(names?: array)
Read last/next run state for the named syncs (fan-out: one `sync-status` per sync, named `sync-status:<name>`). Empty `names` checks all syncs. Surfaces lastSyncStatus/lastSyncError/lastSyncCommit, the missing gitops health view.
ArgumentTypeDescription
names?arraySync names to check; empty means all
fn project_list()
List Arcane compose projects (factory: one `project` per entry, named `project:<name>`)
fn project_validate(target?: string, composePath?: string, composeContent?: string, envPath?: string, envContent?: string)
Validate compose content LOCALLY with `docker compose config` (fail-closed and read-only: no Arcane mutation). Takes composePath/envPath or inline composeContent/envContent.
ArgumentTypeDescription
target?stringLabel for the result (defaults to composePath or 'inline')
composePath?stringPath to a local compose file
composeContent?stringInline compose content (instead of composePath). Not sensitive: put secrets in envContent and reference them as ${VAR}
envPath?stringPath to a local .env file
envContent?stringInline .env content (instead of envPath); may carry secrets, so it is marked sensitive
fn project_get(name: string)
Read a compose project's full detail (compose + env content, status, gitOps mode) into a `project-detail` resource. Used for rollback snapshots.
ArgumentTypeDescription
namestringProject name
fn project_create(name: string, composePath?: string, composeContent?: string, envPath?: string, envContent?: string)
Create a compose project in Arcane (direct mode), pushing compose content via the API. Validates locally first and stops if validation fails or cannot run.
ArgumentTypeDescription
namestringProject name
composePath?string
composeContent?string
envPath?string
envContent?string
fn project_update(name: string, composePath?: string, composeContent?: string, envPath?: string, envContent?: string)
Update a compose project's content in Arcane (direct mode). Validates locally first and stops if validation fails or cannot run. Does NOT redeploy; use project_redeploy or project_deploy.
ArgumentTypeDescription
namestringProject name
composePath?string
composeContent?string
envPath?string
envContent?string
fn project_deploy(name: string, composePath?: string, composeContent?: string, envPath?: string, envContent?: string, rollback?: boolean, healthTimeoutSec?: number, pollIntervalSec?: number)
Validated, mode-aware deploy of a compose project. Snapshots prior state, applies, polls health, and rolls back by default on failure.
ArgumentTypeDescription
namestringProject name
composePath?stringDirect mode: new compose file to deploy
composeContent?stringDirect mode: inline compose content. Not sensitive: put secrets in envContent and reference them as ${VAR}
envPath?string
envContent?string
rollback?booleanRoll back to prior state on failure (direct mode). false = stop and report, leaving the failed state for inspection.
healthTimeoutSec?numberHow long the redeploy and the wait for the project to become healthy may take together. A rollback gets the same time again.
pollIntervalSec?number
fn swarm_service_list()
List swarm services (factory: one `swarm-service` per entry, named `swarm-service:<name>`)
fn swarm_service_get(name: string)
Get a single swarm service by name
ArgumentTypeDescription
namestring
fn swarm_service_rollback(name: string)
Roll a swarm service back to its previous spec (Arcane POST .../rollback)
ArgumentTypeDescription
namestring
fn swarm_service_force_update(name: string, convergeTimeoutSec?: number, pollIntervalSec?: number)
Force-redeploy a swarm service via Arcane (bumps spec.TaskTemplate.ForceUpdate + PUT), which recreates its tasks without changing config. Useful after a dependency (e.g. its DB) becomes ready post-deploy. Polls convergence; throws if it does not converge.
ArgumentTypeDescription
namestringSwarm service name (e.g. unifi_unifi)
convergeTimeoutSec?number
pollIntervalSec?number
fn swarm_stack_list()
List swarm stacks (factory: one `swarm-stack` per entry, named `swarm-stack:<name>`)
fn swarm_stack_get(name: string)
Get a single swarm stack by name
ArgumentTypeDescription
namestring
fn swarm_stack_validate(name: string, composePath?: string, composeContent?: string, envPath?: string, envContent?: string)
Validate a swarm stack via Arcane's config render (POST /swarm/stacks/config/render).
ArgumentTypeDescription
namestringStack name
composePath?string
composeContent?string
envPath?string
envContent?string
fn swarm_stack_deploy(name: string, composePath?: string, composeContent?: string, envPath?: string, envContent?: string, prune?: boolean, convergeTimeoutSec?: number, pollIntervalSec?: number)
Validated deploy of a swarm stack: render (any render error stops the deploy) -> POST the stack -> poll service convergence.
ArgumentTypeDescription
namestringStack name
composePath?string
composeContent?string
envPath?string
envContent?string
prune?booleanRemove services no longer present in the compose file
convergeTimeoutSec?number
pollIntervalSec?number
fn swarm_stack_remove(name: string, removeTimeoutSec?: number, pollIntervalSec?: number)
Remove a swarm stack by name (docker stack rm via Arcane) and confirm the stored record is cleared.
ArgumentTypeDescription
namestring
removeTimeoutSec?numberMax seconds to keep re-issuing DELETE until the stack record 404s
pollIntervalSec?number
fn swarm_stack_tasks(name: string, onlyProblems?: boolean)
List a swarm stack's tasks (factory: one `swarm-task` per task, named `swarm-task:<task id>`) with per-task currentState + error: the deploy debug view that surfaces rejected/failed reasons (missing bind path, non-zero exit, placement).
ArgumentTypeDescription
namestringStack name
onlyProblems?booleanEmit only tasks whose currentState is rejected/failed/orphaned (the error-bearing ones)
fn volume_list()
List docker volumes (factory: one `volume` per entry, named `volume:<name>`). Includes `inUse` so orphaned volumes are visible.
fn volume_remove(name: string)
Remove a docker volume by name. Idempotent: a volume that is already gone counts as removed. An in-use volume is refused and left in place; stop or remove the containers using it first.
ArgumentTypeDescription
namestring
fn volume_prune()
Prune UNUSED anonymous docker volumes (Docker default: named volumes are NOT removed). Removes only volumes no container references. For a specific named volume use volume_remove.
fn network_prune()
Prune unused docker networks (no attached containers). Safe: only removes networks nothing is using.
fn image_prune(dangling?: boolean)
Prune unused images. dangling:true (default) removes only dangling layers; dangling:false removes ALL images not referenced by a container.
ArgumentTypeDescription
dangling?booleantrue = only dangling layers (safe); false = all unused images

Resources

repository(infinite)— An Arcane git repository connection
sync(infinite)— An Arcane GitOps sync entry (one project pulled from git)
sync-status(infinite)— A GitOps sync's last/next run state (lastSyncStatus/lastSyncError/lastSyncCommit): the gitops health view
arcane-version(infinite)— Arcane's reported version (current + newest available), for checks before and after an upgrade
project(infinite)— An Arcane compose project
operation-result(infinite)— Result of a mutating Arcane operation (sync trigger, project lifecycle)
project-detail(infinite)— A compose project's full detail incl. compose/env content (rollback snapshot)
validation(infinite)— Result of a local compose validation (`docker compose config`)
swarm-secret(infinite)— A swarm secret (immutable; rotate via secret_rotate)
swarm-config(infinite)— A swarm config (immutable; rotate via config_rotate)
swarm-service(infinite)— A swarm service summary
swarm-stack(infinite)— A swarm stack (a deployed compose stack)
swarm-stack-render(infinite)— Result of Arcane's swarm-stack config render: the mandatory pre-deploy validation gate
swarm-task(infinite)— A swarm task (a replica placement attempt) with state + error: the deploy debug view
volume(infinite)— A docker volume (incl. inUse, for spotting orphans)
prune-result(infinite)— Result of a docker prune (space reclaimed + deleted items)
03Previous Versions4
2026.06.24.1

Removed 1 behaviors

2026.05.24.1

Repairs the broken 2026.05.23.1 release, which shipped a version bump without its matching upgrades[] migration entry and left the @thomas/arcane type unloadable ("Last upgrade toVersion 2026.05.22.1 does not match model version 2026.05.23.1"). Adds the no-op migrations for .23.1 and .24.1; globalArguments schema is unchanged. .23.1 is yanked in favour of this version.

2026.05.23.1yanked
2026.05.22.1
04Stats
A
93 / 100
Downloads
32
Archive size
66.3 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License1/2partial

    no SPDX license declared

  • Verified public repository2/2earned
05Platforms
06Labels