Gateway

The gateway is the resident Anyy runtime. It owns long-lived state and brokers access from the TUI, CLI chat, dashboard, channels, cron, and background work.

The fast path does not require you to start a service first: running anyy opens the TUI and starts an embedded gateway when needed. Start the resident gateway when you want Anyy to stay available after the TUI exits, or when you want one-shot chat, channels, dashboard, and scheduled work to keep running.

When To Run It

Workflow	Gateway mode
Interactive terminal use only	Run anyy; the TUI starts an embedded gateway when needed.
One-shot shell prompts with anyy chat	Start the resident gateway first.
Messaging channels	Run the resident gateway so adapters can receive and reply.
Cron, heartbeat, and background delivery	Run the resident gateway continuously.
Dashboard access outside the TUI	Run the resident gateway and dashboard sidecar.

What The Gateway Owns

The gateway owns runtime concerns that should not live inside a single client:

• Session creation, resume, active turns, queueing, stopping, branching, and compression.
• Context assembly for each turn.
• Provider/model runtime state and fallback handling.
• Tool registry, toolsets, approvals, ChangePlans, and audit events.
• Messaging channel adapters and channel reload.
• Cron, heartbeat, background jobs, and session inbox/outbox delivery.
• RPC status, diagnostics, and local event streaming.

Clients connect to it; they do not own the agent loop or durable session state.

Start And Stop

Start the resident gateway:

anyy gateway start

Check it:

anyy gateway status
anyy status

Restart after changing gateway-level configuration or upgrading the binary:

anyy gateway restart

Stop it:

anyy gateway stop

All four commands accept --home PATH, and the global --profile / --profile-root flags select the profile before the home is resolved.

Install As A Service

anyy gateway start manages the background service for the resolved home. If no supported service is installed yet, it installs one and then waits for the gateway RPC endpoint to become reachable.

Supported service hosts in the current implementation are:

Host	Label shown by status
macOS launchd user service	launchd user service
Linux systemd user service	systemd user service
procd	procd service

On unsupported hosts, the command reports that gateway service management is not available. The TUI embedded gateway still works for interactive local use.

Unix Socket

The profile home contains the default Unix-domain socket:

<home>/anyy.sock

Most local clients use that socket by default. Override it only when a command explicitly supports --socket PATH:

anyy status --socket /path/to/anyy.sock
anyy chat --socket /path/to/anyy.sock "Hello"

The gateway config also has TCP listener fields. Do not assume a listener is safe just because it is local in your setup; check the effective config and runtime status:

anyy status --json

For config fields and defaults, see Configuration Reference. For exposure and token guidance, see Security & Privacy.

RPC Boundary

RPC is the transport boundary between clients and the resident runtime. TUI, CLI chat, dashboard, channels, and internal service entrypoints call gateway RPC methods for sessions, commands, status, approvals, tools, profiles, roles, MCP, channels, and diagnostics.

This boundary keeps the client surfaces thin. A dashboard or chat adapter can request a session turn, but the gateway still owns context assembly, tool governance, approvals, and persistence.

Session Queue

Only one turn should actively drive a session at a time. When input arrives while a turn is running, the runtime uses command behavior to decide what happens:

Behavior	Example
Queue behind the running turn	/queue or normal input when busy mode is queue.
Steer the running turn	/btw or /steer.
Stop the running turn	/stop, TUI interrupt, or session stop RPC.
Reject while running	/branch, /compress, /retry, and similar commands.

The queue is per session, so one busy conversation does not block unrelated sessions.

Channel Runtime

Messaging channels run inside the resident gateway. After changing channel configuration, either restart the gateway or reload channel adapters:

anyy channels reload

Channel doctors run outside the gateway and verify local readiness for a single channel:

anyy channels doctor telegram

For channel-specific setup, start with Messaging Gateway and the Channels Reference.

Background Jobs

The gateway owns work that can outlive a single foreground reply: cron jobs, heartbeat checks, background child agents, managed shell/process jobs, channel delivery, and session inbox/outbox records.

Useful entry points:

anyy cron list
anyy heartbeat status

Inside the TUI, /background, /agents, /jobs, and /job expose background work for the current session.

Logs And Status

Use service-level status when you care whether the resident process is installed and reachable:

anyy gateway status

Use runtime status when you want profile, role, home, timezone, subsystem, and gateway listener summaries:

anyy status
anyy status --json

Use doctor for local diagnostics:

anyy doctor
anyy doctor --json

The gateway writes local logs under the profile home. The TUI /logs command shows recent local lines, while debug bundles and diagnostics redact known secrets before output.

Common Failure Modes

Symptom	What to check	Typical fix
TUI works but anyy chat fails	anyy gateway status	Start or restart the resident gateway for the same profile/home.
Service management is unsupported	anyy gateway status --home PATH	Use the embedded TUI gateway, or run on a launchd, systemd user, or procd host.
Status shows a version mismatch	Command and running process versions	Run anyy gateway restart after updating the binary.
Socket cannot be reached	anyy status --socket PATH and <home>/runtime.json	Use the resolved socket path or restart the gateway.
Wrong sessions or config appear	Resolved profile/home in anyy status	Pass --profile NAME or --home PATH explicitly.