Deploying

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

akos 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:

akos publish --unsigned

publish options

Deploying a bundle

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

akos deploy

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

To verify only without publishing:

akos deploy --dry-run

deploy options

Installing a plugin

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

akos 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)
akos install <registry-url> --allow-unsigned
 
# Declare permitted permissions
akos install <registry-url> --allow-permission files:read --allow-permission network:egress
 
# Override install root
akos 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.

akos 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:

akos serve --public

Pin the webhook port:

akos 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:

akos 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.

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

To preview the migration plan without writing any data:

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

To resume a previously interrupted migration:

akos 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
 
akos migrate-to-cloud \
  --org my-org-id \
  --source ~/.agentskit \
  --target postgres://...

migrate-to-cloud options

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.

akos snapshot schedule

Customize the schedule and retention:

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

snapshot schedule options

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
akos telemetry status
 
# Opt in
akos telemetry enable
 
# Opt out
akos telemetry disable
 
# Export stored events (JSON by default)
akos telemetry export
 
# Export as CSV
akos telemetry export --csv
 
# Export events since a specific date
akos telemetry export --since 2024-01-01T00:00:00Z
 
# Preview event counts without printing values
akos telemetry export --dry-run