jus-agent v0.3.4

Installing jus-agent

jus-agent is the remote dispatch agent for Juscribe. It connects to the Juscribe server via WebSocket and executes Claude Code dispatches on your dev machine.

Platform support: This version of jus-agent is supported on macOS with OrbStack and Claude Code CLI. Linux and Windows support is coming soon — binaries are provided but not yet officially supported.

Install via Homebrew (recommended)

brew install juscribe/tap/jus

This installs both the jus CLI and the jus-agent binary. Skip to Setup.

Manual download

Download the binary for your platform from the latest release:

# macOS — Apple Silicon (M1/M2/M3/M4)
curl -L https://github.com/juscribe/jus-agent/releases/download/v0.3.4/jus-agent-darwin-arm64 -o jus-agent

# macOS — Intel
curl -L https://github.com/juscribe/jus-agent/releases/download/v0.3.4/jus-agent-darwin-amd64 -o jus-agent

# Linux — x86_64
curl -L https://github.com/juscribe/jus-agent/releases/download/v0.3.4/jus-agent-linux-amd64 -o jus-agent

# Linux — ARM64
curl -L https://github.com/juscribe/jus-agent/releases/download/v0.3.4/jus-agent-linux-arm64 -o jus-agent

Make it executable and move to your PATH:

chmod +x jus-agent
sudo mv jus-agent /usr/local/bin/

/usr/local/bin/ is a suggestion — the binary can live anywhere on your $PATH. For example, ~/.local/bin/ works if you prefer to avoid sudo. Just make sure the directory is in your $PATH.

Setup

Run the interactive setup wizard:

jus-agent init

The wizard prompts you for each setting. Press Enter to accept the default (shown in brackets):

Prompt	Default	What it means
API token	(none — required)	Your Juscribe API token. Find this in your workspace under Settings → API Tokens. This authenticates the agent with the server.
Server URL	wss://app.juscribe.ai/cable	The WebSocket endpoint for your Juscribe instance. Accept the default unless you have a designated subdomain.
Project path	Current directory	Absolute path to the Git repository the agent will work in. Dispatched Claude sessions run inside this repo.
Sandbox mode	raw	How dispatched sessions are isolated. raw runs directly on your machine. orbstack runs inside an OrbStack VM for stronger isolation (macOS only — run jus-agent setup-orb first).
OrbStack target	(only shown if sandbox = orbstack)	Name of the OrbStack orb to use for sandboxed execution.
Log level	info	Verbosity: debug, info, warn, or error. Use debug when troubleshooting connection or dispatch issues.

Config is saved to ~/.config/jus-agent/config.toml. All values can be overridden at runtime via flags (--token, --server, etc.) or environment variables (JUS_API_TOKEN, JUS_SERVER_URL, JUS_PROJECT_PATH, JUS_SANDBOX_MODE).

Usage

Start the agent:

jus-agent start

The agent connects to your Juscribe workspace via WebSocket and listens for dispatch commands. When you click Dispatch on a ticket in the Juscribe UI, the agent:

1. Receives the dispatch payload (ticket prompt, configuration)
2. Creates a Git worktree for isolated execution (on branch-based strategies)
3. Spawns a Claude Code CLI session with the ticket prompt
4. Streams heartbeats and status updates back to the workspace in real time
5. Reports the result (success, failure, or error) when the session completes
6. Merges the worktree branch back to main and cleans up

The agent runs continuously — leave it running in a terminal tab, tmux session, or behind a process manager. Press Ctrl+C to shut down gracefully (it waits for any active dispatches to finish before exiting).

Other commands

Command	Description
jus-agent version	Print agent and protocol versions
jus-agent setup-orb	Create and configure an OrbStack orb for sandboxed execution
jus-agent init	Re-run the setup wizard (overwrites existing config)

Sandbox modes

By default, dispatched Claude sessions run directly on your machine (raw mode). For stronger isolation, jus-agent supports sandboxed execution — the Claude process runs inside a lightweight VM or container with access to your project files but no access to your host processes, credentials, or tools.

Raw (default)

No sandbox. Claude Code runs directly on your machine as your user. Simplest setup, no extra dependencies. Best for trusted workspaces or when you want full access to your local toolchain (Homebrew, rbenv, etc.).

OrbStack (macOS only)

Runs Claude Code inside an OrbStack Linux VM. OrbStack is a fast, lightweight alternative to Docker Desktop for macOS. Your project directory is shared into the VM automatically, but the process is isolated from your host.

Prerequisites: Install OrbStack first.

# Create and configure an orb with Claude Code installed
jus-agent setup-orb

# Start with sandbox enabled
jus-agent start --sandbox orbstack

setup-orb creates an Ubuntu orb, installs Claude Code inside it, verifies networking (the orb can reach your host via host.internal), and updates your config. You only need to run it once.

Docker (coming soon)

Docker container sandbox support is planned but not yet implemented. If you need container-based isolation today, OrbStack is the recommended option on macOS.

Verify

After starting, check the Juscribe workspace — you should see a green agent indicator in the header. If this is the only agent connected, you'll see a green dot; if multiple agents are connected, the dot is replaced by a count badge showing the number of online agents. Hover over the indicator to see the names of connected agents. Dispatches will route to your agent when the workspace dispatch mode is set to "agent".

Configuration

The config file lives at ~/.config/jus-agent/config.toml:

[server]
url = "wss://app.juscribe.ai/cable"
token = "your-bot-api-token"

[project]
path = "/path/to/your/project"

[sandbox]
mode = "raw"           # "raw" (direct) or "orbstack" (sandboxed)
target = "jus-sandbox" # orb name (only for orbstack mode)

[execution]
claude_path = "claude"
max_turns = 200
heartbeat_interval = "30s"

[logging]
level = "info"
file = "~/.local/share/jus-agent/logs/jus-agent.log"

Log file

By default, jus-agent writes logs to both stderr and a persistent log file at:

~/.local/share/jus-agent/logs/jus-agent.log

The log directory is created automatically on first run. The file is opened in append mode, so logs accumulate across restarts.

Customizing the log file path

Three ways to override the default location (listed in precedence order — highest wins):

1. CLI flag: --log-file /path/to/agent.log
2. Environment variable: JUS_LOG_FILE=/path/to/agent.log
3. Config file: set file under [logging] in ~/.config/jus-agent/config.toml

To disable file logging entirely, set the path to an empty string via the env var or flag:

JUS_LOG_FILE="" jus-agent start

If the log file cannot be opened (e.g. permission denied), the agent prints a warning to stderr and continues with stderr-only logging.

Updating

Homebrew

brew upgrade jus

Manual

Download the latest binary and replace the existing one:

# Apple Silicon
curl -L https://github.com/juscribe/jus-agent/releases/download/v0.3.4/jus-agent-darwin-arm64 -o jus-agent
chmod +x jus-agent
sudo mv jus-agent /usr/local/bin/

Restart the agent after updating.