Your first workspace

This guide acquires a dependency-ready worktree, runs a command inside it, and returns it to Ruk's reusable pool.

1. Start in the source repository

Run acquire from any worktree in the target Git repository:

ruk acquire agent/auth-flow --owner agent-17 --json

Ruk either reuses an available managed workspace or creates a new detached Git worktree. It switches that worktree to agent/auth-flow, prepares dependencies, and assigns the workspace to agent-17.

The JSON response contains the two values you must retain:

{
  "status": "assigned",
  "assignmentId": "46bc4998-95b0-4d16-b017-69b06a13747b",
  "path": "/absolute/path/to/workspace",
  "branch": "agent/auth-flow",
  "expiresAt": "2026-08-04T05:00:00.000Z",
  "reused": false,
  "fingerprint": "sha256 dependency fingerprint",
  "mode": "bun-global-store"
}

2. Work at the returned path

cd /absolute/path/to/workspace
ruk run -- bun test

ruk run checks dependency inputs and projection integrity before starting the command. Inside an assigned workspace, it also records the child process so release can clean it up safely. While the command remains active, Ruk renews the assignment automatically.

Use the repository's normal Git workflow. Commit or otherwise save every file you intend to keep before release.

3. Inspect the workspace

ruk status --json

A ready assigned workspace reports its lifecycle, assignment ID, expiry, latest activity, automatic-renewal status, and current dependency fingerprint.

4. Release the exact assignment

ruk release 46bc4998-95b0-4d16-b017-69b06a13747b --json

Release stops recorded child processes, cleans the worktree, detaches it, and returns it to the pool.

Save work before release

Release removes tracked, untracked, and ignored files before the workspace becomes available. A dirty workspace blocks normal release; --force discards its changes.

Longer work

Assignments default to an eight-hour idle window. Active Ruk-managed commands renew automatically. Renew explicitly when work continues outside those commands, such as a long editor-only session:

ruk renew 46bc4998-95b0-4d16-b017-69b06a13747b --json

Read Assignments and renewal for lease and recovery rules.