# Operations
> Source: https://useagentos.dev/docs/core/operations

This guide covers day-two commands: sessions, cron, cost, diagnostics, replay,
migration, durable agents, MCP, and install inventory. Use it after the first
successful chat or gateway run. To operate a gateway on another machine, see
[Remote Access](https://useagentos.dev/docs/core/remote-access).

## Sessions

Sessions are durable chat/task histories. Use them to resume, inspect, export,
or clean up prior work.

```sh
agentos sessions list
agentos sessions show <session-key>
agentos sessions resume <session-key>
agentos sessions export <session-key>
agentos sessions abort <session-key>
agentos sessions delete <session-key>
```

Use session export when exact old context matters or when you want to debug a
long-running task outside the chat UI.

For resume, abort, export, and cleanup workflows, see
[Sessions and History](https://useagentos.dev/docs/core/sessions).

## Durable Agents

AgentOS supports durable agent entries, including the built-in `main`
agent.

```sh
agentos agents list
agentos agents add research --name Research --workspace /path/to/research
agentos agents delete research
```

Use durable agents when you want separate workspaces, instructions, or tool
profiles for recurring roles. Restart the gateway after agent config changes.

Keep each durable agent's instructions focused on that role instead of turning
every agent into a copy of `main`.

For agent examples and concepts, see [Durable Agents](https://useagentos.dev/docs/core/agents).

## Cron and Scheduled Runs

Cron jobs run AgentOS tasks on a schedule.

Inspect jobs:

```sh
agentos cron list
agentos cron status <job-id>
agentos cron runs <job-id>
```

Add a simple recurring reminder:

```sh
agentos cron add \
  --every 1h \
  --text "Check for urgent project updates and summarize them" \
  --name hourly-project-check
```

Add a daily cron-style task:

```sh
agentos cron add \
  --cron "0 9 * * 1-5" \
  --tz "America/Los_Angeles" \
  --text "Prepare my weekday morning briefing" \
  --name weekday-briefing
```

Manage jobs:

```sh
agentos cron update <job-id> --enabled
agentos cron remove <job-id>
agentos cron run <job-id>
```

Good uses:

- morning briefings;
- recurring research digests;
- PR or CI checks;
- channel-delivered reminders;
- scheduled memory consolidation or reporting tasks.

Pair cron with channels when the output should be delivered somewhere other
than the local Web UI.

For scheduling examples, delivery options, and troubleshooting, see
[Scheduling](https://useagentos.dev/docs/core/scheduling).

## Cost and Usage

Inspect usage and estimated cost:

```sh
agentos cost
agentos cost --by-model
agentos cost --json
```

Use cost inspection after tool-heavy, routed, or long-context tasks to
understand actual runtime behavior.

For cost investigation workflow, see [Usage and Cost](https://useagentos.dev/docs/core/usage-and-cost).

## Always-On Gateway

For a gateway that should keep running unattended (a home server, a laptop
that sleeps), install it as a user service and let it watch itself:

```sh
agentos gateway install --port 18791
agentos gateway status --deep --json
curl -s http://127.0.0.1:18791/ready
agentos channels status --json
```

- **Restarts.** launchd (macOS) or systemd (Linux) restarts the gateway when it
  dies; a configuration error (exit `78`) is not restarted into a loop by
  systemd. See [Run as a service](https://useagentos.dev/docs/core/gateway#run-as-a-service).
- **Crash loops.** Three unclean boots in five minutes start the gateway in
  safe mode: channels, cron and heartbeat are held back, `/ready` reports
  `state: "safe_mode"`, and `agentos doctor` names the way out. Fix the cause,
  then `agentos channels start --yes`, or let it clear by itself after five
  quiet minutes.
- **Sleep.** After the machine wakes, the gateway restarts idle channels
  (`gateway.thaw` in the log; a restart that fails while the network comes
  back is retried with backoff) and runs each overdue cron job once. A
  5-minute health sweep restarts channels that are `disconnected`, `stuck`,
  `start_failed` or `stale-socket`; one stopped on bad credentials
  (`terminal`) waits for you — doctor shows the fix.
- **Missed jobs.** Agent jobs missed while the gateway was down run
  `[scheduler] startup_agent_delay_seconds` (default 120) after boot; see
  [Scheduling](https://useagentos.dev/docs/core/scheduling).
- **Stopping.** A stop drains active turns for up to 30 s, then cancels the
  rest (`drain_budget_ms` in `agentos gateway status --json`); the service
  units allow 54 s (the worst-case stop plus a margin) before they kill. Stop a service-run gateway through the
  service (`agentos gateway stop` tells you how) or remove it with
  `agentos gateway uninstall`.

## Diagnostics

Diagnostics help explain runtime behavior without changing the core task.

```sh
agentos diagnostics status
agentos diagnostics on
agentos diagnostics off
```

Use diagnostics when investigating:

- provider retry behavior;
- router decisions;
- cache breaks;
- compaction events;
- tool-result compression;
- channel delivery failures.

Turn diagnostics off after collecting the needed evidence.

For diagnostics guidance and safe sharing notes, see
[Diagnostics and Replay](https://useagentos.dev/docs/core/diagnostics-and-replay).

## Replay

Replay a recorded turn from the decision log:

```sh
agentos replay --session <session-key> --turn <turn-id>
```

Replay is useful for reproducing an agent turn, reviewing decision metadata, or
debugging behavior after the original chat has moved on.

## Migration

Preview first:

```sh
agentos migrate openclaw --json
agentos migrate hermes --json
```

Apply after reviewing the report:

```sh
agentos migrate openclaw --apply
agentos migrate hermes --apply
```

See [MIGRATION.md](https://github.com/use-agent-os/agent-os/blob/main/MIGRATION.md) for custom paths and conflict
handling.

## MCP Server

AgentOS can run an MCP server bridge:

```sh
agentos mcp-server run
```

The MCP SDK is a core dependency, so a standard install from the
[Installation](https://useagentos.dev/docs/core#installation) section of the README is enough; there
is no `mcp` extra.

Use this when another MCP-capable client should access AgentOS-managed tools
or runtime surfaces.

For setup details, see [MCP Server Bridge](https://useagentos.dev/docs/core/mcp-server).

## Install Inventory

Emit a reproducible workspace-state inventory:

```sh
agentos dist
agentos dist --output workspace-state.json
agentos dist -o ./support/workspace-state.json
```

With no flags the payload prints to stdout. `--output` (`-o`) writes the
payload to the given file instead (creating parent directories) and prints
the resolved path so shell pipelines can capture it.

The payload is a versioned JSON document:

```jsonc
{
  "schema_version": 1,
  "agentos_version": "<installed version>",
  "python_requires": ">=3.12",
  "bundled_channels": ["discord", "email", "slack", "telegram", ...],
  "bundled_tools": ["agents", "code_exec", "filesystem", "git", ...],
  "gateway_defaults": {"listen": "127.0.0.1", "port": 18791}
}
```

It is built only from installed package metadata plus hard-coded
constants, so two calls from the same install produce byte-identical JSON
(sorted keys, stable indent). It carries no environment values, file
paths, timestamps, or secrets — safe to attach to support requests.

Use this for support, release QA, or environment comparison.

## Models

Inspect available models:

```sh
agentos models list
```

In this build, model inspection can be runtime-backed. If it cannot connect,
start the gateway first:

```sh
agentos gateway run
```

For provider catalog inspection that does not require a live gateway, use:

```sh
agentos providers list
```

Read: [Providers and Models](https://useagentos.dev/docs/core/providers-and-models)

## Health Checklist

For a confusing install or runtime:

```sh
agentos doctor
agentos gateway status
agentos gateway status --deep --json
agentos providers list
agentos search list
agentos channels types
agentos sandbox status
```

Then turn on diagnostics only if the basic health surfaces are not enough.
