Streaming Sessions

Everything you need to know about manual terminal streams.

Basic Usage

The afk stream command starts a streamed session. With no command, AFK uses your $SHELL and falls back to sh:

afk stream

afk stream -- <your-command>

Use streams when you want a terminal, agent, build, or deploy to appear on iOS or web. The -- separator passes any flags through to your command instead of letting afk swallow them.

Common Examples

AFK is built for interactive sessions — shells and AI coding agents you want to drive from your phone. It's not designed for batch jobs like one-shot builds, test runs, or log tails.

Shells

Stream a bash or zsh session and use it like any other terminal from your phone:

afk stream -- bash

afk stream -- zsh

AI coding agents

Drive Claude Code, Codex, or Gemini CLI from your phone — review diffs, approve prompts, and reply by voice or text:

afk stream -- claude

afk stream -- codex

afk stream -- gemini

How It Works

  1. 1
    AFK CLI starts

    AFK creates a pseudo-terminal (PTY) and runs your command inside it

  2. 2
    Output captured

    Everything the command outputs is captured by AFK

  3. 3
    Encrypted & streamed

    Output is encrypted with your session key and sent to connected devices

  4. 4
    Input sent back

    When you type on mobile, keystrokes are encrypted and sent back to the PTY

Session Options

# Use a specific session ID (useful for scripting)

afk stream --session-id 550e8400-... -- bash

 

# Force re-login before streaming

afk stream --login -- claude

 

# Logout and delete stored tokens

afk stream --logout

Detaching

You can detach from a running session without stopping it. The session continues running in the background.

Escape Sequence: ~.

Press Enter, then ~, then . to detach. The session keeps running and can be reattached later.

# Reconnect to the detached session

afk connect

See Sessions & Connect for more details on reattaching.

Session Lifecycle

Active

Command is running, connected devices can view and interact

Idle

Command waiting for input (e.g., bash prompt)

Detached

You disconnected locally, but the session is still running. Reconnect with afk connect

Sleeping

The session is running but the desktop machine has gone to sleep or is idle. The session will resume when the machine wakes up

Disconnected

The desktop wrapper lost its connection to the backend. This may indicate a network issue or that the desktop went offline

Closed

Command exited, session ends. Mobile clients receive a notification when a session closes

Sessions end when the wrapped command exits (e.g., typing exit in bash).

Tips

  • • Start a separate afk stream for each terminal session you want to see from your devices
  • • Use afk stream -- bash for manual general shell access - you can run any commands inside
  • • Each session gets a unique ID shown when you start it