Arcane
@thomas/arcanev2026.05.23.1
01README
Management of an Arcane Docker instance via its REST API — GitOps sync setup, compose project lifecycle with validated mode-aware deploy, swarm stack deploy (render-validated, convergence-polled) + secret/config rotation, and volume/prune cleanup.
02Models
@thomas/arcanev2026.05.23.1arcane.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| baseUrl | string | Arcane base URL including port, e.g. https://arcane-tylo.smol.cloud:8443 |
| apiKey | string | Arcane API key (X-API-Key). Supply via vault: ${{ vault.get(name, key) }} |
| environmentId | string | Arcane environment id; 0 is the local Docker environment |
| skipTlsVerify | boolean | Accept self-signed certs (default false — a valid cert is expected) |
| syncs | array | Desired GitOps sync entries, reconciled by gitops_sync_ensure |
fn gitops_repo_list()
List Arcane git repository connections (factory: one `repository` per entry, keyed by 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_sync_list()
List Arcane GitOps syncs (factory: one `sync` per entry, keyed by name)
fn gitops_sync_ensure(prune: boolean)
Reconcile GitOps syncs from globalArgs.syncs against Arcane (create missing, update drifted). With prune=true, deletes syncs not in the desired list.
| Argument | Type | Description |
|---|---|---|
| prune | boolean | Delete existing syncs whose name is not in globalArgs.syncs (destructive) |
fn gitops_sync_trigger(names: array)
Trigger a git pull for the named syncs (fan-out). Empty `names` triggers all syncs.
| Argument | Type | Description |
|---|---|---|
| names | array | Sync names to trigger; empty means all |
fn project_list()
List Arcane compose projects (factory: one `project` per entry, keyed by name)
fn project_validate(target?: string, composePath?: string, composeContent?: string, envPath?: string, envContent?: string)
Validate compose content LOCALLY with `docker compose config` (fail-closed, read-only — no Arcane mutation). Takes composePath/envPath or inline composeContent/envContent.
| Argument | Type | Description |
|---|---|---|
| target? | string | Label for the result (defaults to composePath or 'inline') |
| composePath? | string | Path to a local compose file |
| composeContent? | string | Inline compose content (instead of composePath) |
| envPath? | string | Path to a local .env file |
| envContent? | string | Inline .env content (instead of envPath) |
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.
| Argument | Type | Description |
|---|---|---|
| name | string | Project name |
fn project_create(name: string, composePath?: string, composeContent?: string, envPath?: string, envContent?: string, validate: boolean)
Create a compose project in Arcane (direct mode), pushing compose content via the API. Validates locally first (fail-closed unless validate:false).
| Argument | Type | Description |
|---|---|---|
| name | string | Project name |
| composePath? | string | |
| composeContent? | string | |
| envPath? | string | |
| envContent? | string | |
| validate | boolean | Run local compose validation before pushing (fail-closed) |
fn project_update(name: string, composePath?: string, composeContent?: string, envPath?: string, envContent?: string, validate: boolean)
Update a compose project's content in Arcane (direct mode). Validates locally first (fail-closed unless validate:false). Does NOT redeploy — use project_redeploy or project_deploy.
| Argument | Type | Description |
|---|---|---|
| name | string | Project name |
| composePath? | string | |
| composeContent? | string | |
| envPath? | string | |
| envContent? | string | |
| validate | boolean |
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.
| Argument | Type | Description |
|---|---|---|
| name | string | Project name |
| composePath? | string | Direct mode: new compose file to deploy |
| composeContent? | string | Direct mode: inline compose content |
| envPath? | string | |
| envContent? | string | |
| rollback | boolean | Roll back to prior state on failure (direct mode). false = stop and report, leaving the failed state for inspection. |
| healthTimeoutSec | number | How long to wait for the project to become healthy |
| pollIntervalSec | number |
fn swarm_service_list()
List swarm services (factory: one `swarm-service` per entry, keyed by name)
fn swarm_service_get(name: string)
Get a single swarm service by name
| Argument | Type | Description |
|---|---|---|
| name | string |
fn swarm_service_rollback(name: string)
Roll a swarm service back to its previous spec (Arcane POST .../rollback)
| Argument | Type | Description |
|---|---|---|
| name | string |
fn swarm_service_force_update(name: string, convergeTimeoutSec: number, pollIntervalSec: number)
Force-redeploy a swarm service via Arcane (bumps spec.TaskTemplate.ForceUpdate + PUT) — 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.
| Argument | Type | Description |
|---|---|---|
| name | string | Swarm service name (e.g. unifi_unifi) |
| convergeTimeoutSec | number | |
| pollIntervalSec | number |
fn swarm_stack_list()
List swarm stacks (factory: one `swarm-stack` per entry, keyed by name)
fn swarm_stack_get(name: string)
Get a single swarm stack by name
| Argument | Type | Description |
|---|---|---|
| name | string |
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).
| Argument | Type | Description |
|---|---|---|
| name | string | Stack 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 (fail-closed, guardrail #2) -> POST the stack -> poll service convergence.
| Argument | Type | Description |
|---|---|---|
| name | string | Stack name |
| composePath? | string | |
| composeContent? | string | |
| envPath? | string | |
| envContent? | string | |
| prune | boolean | Remove 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.
| Argument | Type | Description |
|---|---|---|
| name | string | |
| removeTimeoutSec | number | Max 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) with per-task currentState + error — the deploy debug view that surfaces rejected/failed reasons (missing bind path, non-zero exit, placement).
| Argument | Type | Description |
|---|---|---|
| name | string | Stack name |
| onlyProblems | boolean | Emit only tasks whose currentState is rejected/failed/orphaned (the error-bearing ones) |
fn volume_list()
List docker volumes (factory: one `volume` per entry, keyed by name). Includes `inUse` so orphaned volumes are visible.
fn volume_remove(name: string, force: boolean)
Remove a docker volume by name. Idempotent (404 = already gone). An in-use volume returns 409 and is surfaced, NOT forced — unless force:true, which bypasses the in-use guard (discouraged, guardrail #5 — risks data loss).
| Argument | Type | Description |
|---|---|---|
| name | string | |
| force | boolean | Force removal even if Docker reports the volume in use (discouraged) |
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.
| Argument | Type | Description |
|---|---|---|
| dangling | boolean | true = 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)
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 Versions
2026.05.22.1May 22, 2026
04Stats
A
100 / 100
Downloads
0
Archive size
53.6 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
05Platforms
06Labels