---
title: Deploying
description: 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

```bash
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:

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

```bash
akos deploy
```

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

To verify only without publishing:

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

```bash
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>/`.

```bash
# 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.

```bash
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:

```bash
akos serve --public
```

Pin the webhook port:

```bash
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:

```bash
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.

```bash
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:

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

To resume a previously interrupted migration:

```bash
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:

```bash
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

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

```bash
akos snapshot schedule
```

Customize the schedule and retention:

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

```bash
# 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
```

## Related topics

- **[Migrating to AKOS](/docs/cli/migrating)** — `migrate-to-cloud` walkthrough (also covered above)
- **[Configuration](/docs/cli/configuration)** — `lock`, `sync`, and workspace export/import
- **[Connections](/docs/cli/connections)** — preflight integrations before go-live
- **[Knowledge and RAG](/docs/cli/knowledge-and-rag)** — `prod seed` for assistant documentation
- **[Command reference](/docs/cli/command-reference)** — `publish`, `install`, `serve`, `mcp-serve`, snapshots