Synk Agent

CLI client for controlling ekkOS Synk agents remotely.

Unlike synk-cli which both runs and controls agents, ekkos-agent only controls them — creating sessions, sending messages, reading history, monitoring state, and stopping sessions.

Installation

From the monorepo:

yarn workspace ekkos-agent build

Or link globally:

cd packages/ekkos-agent && npm link

Authentication

Synk Agent uses account authentication via QR code, the same flow as linking a device in the Synk mobile app.

# Authenticate by scanning QR code with the Synk mobile app
ekkos-agent auth login

# Check authentication status
ekkos-agent auth status

# Clear stored credentials
ekkos-agent auth logout

Credentials are stored at ~/.ekkos/synk/agent.key.

Commands

List sessions

# List all sessions
ekkos-agent list

# List only active sessions
ekkos-agent list --active

# Output as JSON
ekkos-agent list --json

Session status

# Get live session state (supports ID prefix matching)
ekkos-agent status <session-id>

# Output as JSON
ekkos-agent status <session-id> --json

Create a session

# Create a new session with a tag
ekkos-agent create --tag my-project

# Specify a working directory
ekkos-agent create --tag my-project --path /home/user/project

# Output as JSON
ekkos-agent create --tag my-project --json

Send a message

# Send a message to a session
ekkos-agent send <session-id> "Fix the login bug"

# Send and wait for the agent to finish
ekkos-agent send <session-id> "Run the tests" --wait

# Output as JSON
ekkos-agent send <session-id> "Hello" --json

Message history

# View message history
ekkos-agent history <session-id>

# Limit to last N messages
ekkos-agent history <session-id> --limit 10

# Output as JSON
ekkos-agent history <session-id> --json

Stop a session

ekkos-agent stop <session-id>

Wait for idle

# Wait for agent to become idle (default 300s timeout)
ekkos-agent wait <session-id>

# Custom timeout
ekkos-agent wait <session-id> --timeout 60

Exit code 0 when agent becomes idle, 1 on timeout.

Environment Variables

• EKKOS_SYNK_SERVER_URL - API server URL (default: https://synk.ekkos.dev)
• EKKOS_SYNK_HOME_DIR - Home directory for credential storage (default: ~/.ekkos/synk)

Session ID Matching

All commands that accept a <session-id> support prefix matching. You can provide the first few characters of a session ID and the CLI will resolve the full ID.

Encryption

All session data is end-to-end encrypted. New sessions use AES-256-GCM with per-session keys. Existing sessions created by other clients are decrypted using the appropriate key scheme (AES-256-GCM or legacy NaCl secretbox).

Requirements

• Node.js >= 20.0.0
• A Synk mobile app account for authentication

Publishing to npm

Maintainers can publish a new version:

yarn release               # From repo root: choose library to release
# or directly:
yarn workspace ekkos-agent release

This flow:

• runs tests/build checks via prepublishOnly
• creates a release commit and ekkos-agent-vX.Y.Z tag
• creates a GitHub release with generated notes
• publishes ekkos-agent to npm

License

MIT