Deploying

Publish and deploy plugins, run the local sidecar, migrate to cloud, and manage workspace snapshots.

AKOS supports several deployment workflows: publishing plugins for the marketplace, running the local sidecar for development, migrating self-hosted data to cloud infrastructure, and scheduling workspace snapshots.

Publishing a plugin

The publish command packages a plugin into a signed, integrity-verified bundle for the AKOS marketplace.

Plugin structure

Your plugin directory should contain:

agentskit-os.plugin.yaml — the plugin manifest
dist/ — compiled asset files

Build the bundle

agentskit-os publish

By default this reads the manifest from ./agentskit-os.plugin.yaml, packages assets from ./dist/, and writes ./agentskit-os.bundle.json.

For development or internal bundles, skip the signature requirement:

agentskit-os publish --unsigned

publish options

Flag	Description
`[dir]`	Plugin source directory (default: `.`)
`--manifest <path>`	Override manifest path
`--assets <dir>`	Override assets directory
`--out <path>`	Override bundle output path
`--unsigned`	Emit an unsigned manifest (for dev/internal use)
`--registry-url <url>`	POST the bundle to a marketplace publish endpoint
`--publisher-id <id>`	Publisher ID (default: `manifest.id`)

Deploying a bundle

After building with publish, use deploy to verify asset integrity and hand the bundle to a publisher backend.

agentskit-os deploy

By default reads ./agentskit-os.bundle.json and verifies each asset's SHA-256.

To verify only without publishing:

agentskit-os deploy --dry-run

deploy options

Flag	Description
`[bundle]`	Bundle JSON path (default: `agentskit-os.bundle.json`)
`--assets <dir>`	Override assets directory (default: `<bundle-dir>/dist`)
`--publisher <name>`	Publisher backend (default: `in-memory`)
`--dry-run`	Verify only; skip the publish call

Installing a plugin

To fetch, verify, and install a plugin from a registry URL:

agentskit-os install <registry-url>

The CLI fetches the payload (manifest + bundle + signature), verifies the signature, resolves permissions, and writes the plugin to ~/.agentskitos/plugins/<id>/<version>/.

# Allow installation of an unsigned bundle (internal use only)
agentskit-os install <registry-url> --allow-unsigned
 
# Declare permitted permissions
agentskit-os install <registry-url> --allow-permission files:read --allow-permission network:egress
 
# Override install root
agentskit-os install <registry-url> --install-root /opt/akos/plugins

Running the local sidecar

The serve command starts the local workspace sidecar, which provides the JSON-RPC surface that the desktop app and CLI commands such as hitl, triggers, vault, and connections communicate with.

agentskit-os serve

The process stays running and streams JSON-RPC over stdin/stdout. Use this during local development.

To accept webhook deliveries from external systems, bind to all interfaces:

agentskit-os serve --public

Pin the webhook port:

agentskit-os serve --public --webhook-port 4242

When --public is used, the CLI prints a security warning. Always run behind a firewall or trusted tunnel and ensure every webhook trigger verifies its signature.

Exposing the capability catalog over MCP

To allow an external AI agent to query the AKOS capability catalog via the Model Context Protocol:

agentskit-os mcp-serve

Spawns the MCP server over stdio. The external agent connects via JSON-RPC and can call doc.search, doc.get, and capabilities.list.

Migrating from self-hosted to cloud

The migrate-to-cloud command streams your local workspace data (SQLite tables and blob objects) to a cloud Postgres database and optionally an S3 bucket.

agentskit-os migrate-to-cloud \
  --org my-org-id \
  --source ~/.agentskit \
  --target postgres://user:pass@host/dbname

To preview the migration plan without writing any data:

agentskit-os migrate-to-cloud \
  --org my-org-id \
  --source ~/.agentskit \
  --target postgres://... \
  --dry-run

To resume a previously interrupted migration:

agentskit-os migrate-to-cloud \
  --org my-org-id \
  --source ~/.agentskit \
  --target postgres://... \
  --resume

A checkpoint file at <source>/.migrate-checkpoint.json tracks progress. Rows and blobs already migrated are skipped (ON CONFLICT DO NOTHING).

Blob migration (S3)

Set environment variables before running if you want to migrate blob objects alongside relational data:

export AKOS_S3_BUCKET=my-akos-bucket
export AKOS_S3_REGION=us-east-1
 
agentskit-os migrate-to-cloud \
  --org my-org-id \
  --source ~/.agentskit \
  --target postgres://...

migrate-to-cloud options

Flag	Description
`--org <orgId>`	Organization ID to migrate (required)
`--source <path>`	Path to the local data directory (required)
`--target <url>`	Cloud Postgres connection URL (required)
`--dry-run`	Print migration plan only; do not write to target
`--resume`	Resume using the checkpoint file

Snapshot scheduling

The snapshot schedule command writes a snapshot scheduling and retention policy for your workspace. It does not install cron or systemd tasks — it records the configuration and prints a suggested cron line you can install yourself.

agentskit-os snapshot schedule

Customize the schedule and retention:

agentskit-os snapshot schedule \
  --dir ./backups/snapshots \
  --cron "0 3 * * *" \
  --daily 7 \
  --weekly 4 \
  --monthly 12

snapshot schedule options

Flag	Description
`--dir <path>`	Snapshot directory (default: `./.agentskitos/snapshots`)
`--cron <expr>`	Cron expression (default: `0 2 * * *` — 2 AM daily)
`--daily <n>`	Keep snapshots for N distinct days (default: 7)
`--weekly <n>`	Keep snapshots for N distinct ISO weeks (default: 4)
`--monthly <n>`	Keep snapshots for N distinct months (default: 12)

After running, the CLI prints the saved config path and a suggested cron entry to run snapshot retention on the same schedule.

Telemetry

AKOS collects anonymous, opt-in usage telemetry. No secret values are ever included.

# Check current consent status
agentskit-os telemetry status
 
# Opt in
agentskit-os telemetry enable
 
# Opt out
agentskit-os telemetry disable
 
# Export stored events (JSON by default)
agentskit-os telemetry export
 
# Export as CSV
agentskit-os telemetry export --csv
 
# Export events since a specific date
agentskit-os telemetry export --since 2024-01-01T00:00:00Z
 
# Preview event counts without printing values
agentskit-os telemetry export --dry-run

On this page