Persistence and remote access

Nagi keeps panes running in a background server. Your terminal client can detach and reconnect later.

For the local, SSH, and nagi --remote workflows, see How to work with Nagi.

Detach and reattach

Detach the client with ctrl+b q; panes and agents keep running. Reattach by running nagi again. Stop the session and its panes with nagi server stop.

When Nagi starts again after a full server stop, it restores the saved session shape. For what survives detach, server restart, screen history replay, native agent session restore, and live handoff, see Session state and restore.

Named sessions

Use named sessions when you want independent Nagi servers.

nagi session list
nagi session attach work
nagi session attach side-project
nagi session stop work
nagi session delete side-project

A named session has its own panes, tabs, workspaces, sockets, and runtime state. It still shares the same global config file.

Use --json for scripts:

nagi session list --json
nagi session stop work --json
nagi session delete side-project --json

Remote attach over SSH

There are two remote modes; How to work with Nagi compares them. SSH to the server and run nagi there for the tmux-style path. Or attach through SSH from your local machine:

nagi --remote workbox
nagi --remote ssh://you@server:2222

In this mode your local Nagi is a thin client. It connects over SSH, starts or attaches to the remote Nagi server, and streams the UI back to your local terminal. Because the client runs locally, Nagi can bridge local desktop features such as image clipboard paste into the remote session by copying the image to a remote temp file and pasting that path.

By default, nagi --remote uses your local Nagi keybindings for that attach. This keeps local muscle memory even when the remote server has different config. The local keybindings are a snapshot from attach time; detach and reattach after editing local keybindings. Use --remote-keybindings server when you want the remote server config instead. Local custom command keybindings are not sent, because those commands would run on the remote host.

For repeat targets, use your SSH config:

Host workbox
  HostName server.example.com
  User you
  Port 2222

Then attach with:

nagi --remote workbox

Remote attach supports Linux and macOS hosts on x86_64 and aarch64. Nagi prefers a matching nagi already on the remote PATH. Because the public binary channel is disabled, put a reviewed matching build on the remote host before attaching; non-interactive runs fail instead of modifying the host.

Native Windows nagi --remote is not part of the Windows beta. From Windows, SSH into the server and run nagi there.

By default, nagi --remote runs remote setup and the bridge through a temporary SSH config that includes your SSH config first, then adds fallback keepalive settings and a private per-attach control socket for connection reuse. Existing user keepalive settings win. Set [remote].manage_ssh_config = false to use plain ssh without Nagi’s generated config or control socket.

Remote attach uses your normal OpenSSH authentication. If the target uses a passphrase-protected key in a non-interactive shell, script, CI job, or mobile terminal that cannot show the passphrase prompt, load the key into ssh-agent first:

ssh-add
nagi --remote workbox

For any remote authentication failure, verify plain SSH access first with ssh workbox, then run nagi --remote workbox again.

By default, remote attach uses the normal restart/stop flow if it needs to replace or restart a running remote server. To opt into experimental live handoff for a supported running remote server, pass --handoff:

nagi --remote workbox --handoff

If you SSH into the server first and run nagi there, Nagi runs entirely on the server. That mode is useful and simple, but it cannot access your local desktop clipboard beyond normal terminal text paste.

When your local and remote platforms match, Nagi can copy the current local binary for direct source builds. Cross-platform release downloads are disabled until Nagi publishes signed artifacts from its own pipeline.

For local builds or custom binaries, set NAGI_REMOTE_BINARY to a local file path before running remote attach.

NAGI_REMOTE_BINARY=target/release/nagi nagi --remote workbox

Remote named sessions

Use --session with --remote to attach to a named session on the remote host:

nagi --remote workbox --session agents

Direct terminal attach

Full Nagi attach opens the whole workspace UI. Direct attach opens one server-owned terminal in your current terminal.

Direct terminal attach is Unix-only in the Windows beta.

Attach by agent target:

nagi agent attach reviewer

Attach by terminal ID:

nagi terminal attach term_abc123

Direct attach streams the current rendered terminal state, then live ANSI frames. Input goes straight to that terminal.

Detach with ctrl+b q. Send a literal ctrl+b with ctrl+b ctrl+b.

Only one writable direct attach client owns input and resize for a terminal. Use --takeover to replace an existing owner:

nagi terminal attach term_abc123 --takeover

For third-party bridges that only need rendered terminal bytes, use a read-only terminal session observer:

nagi terminal session observe w1:p1 --cols 120 --rows 40

It prints newline-delimited JSON terminal.frame records with base64 ANSI bytes, then a terminal.closed record when the server closes the stream. Multiple observers can watch the same terminal without taking input, resize, scroll, or takeover ownership.

For an interactive bridge, use a writable terminal session controller:

nagi terminal session control w1:p1 --takeover --cols 120 --rows 40

Control mode prints the same newline-delimited frame records and reads newline-delimited JSON commands on stdin. terminal.input sends text or base64 bytes, terminal.resize changes the controller viewport, terminal.scroll scrolls the attached viewport, and terminal.release closes the controller. Only one controller owns input and resize at a time.

Single-process escape hatch

Use --no-session to run Nagi without the background server/client split:

nagi --no-session

This is mainly an escape hatch for debugging or compatibility. The default persistent session mode is the normal path.