agentworks-cli 0.2.1

CLI for orchestrating workspace lifecycle across multiple compute targets

Agentworks CLI

CLI for interacting with Agentworks, the swiss army knife for managing agentic workloads.

The Problem Space

Agentworks is an attempt to address several growing problems around agentic engineering with a single, (hopefully) coherent framework.

These problems are:

Security

Agentic engineering is inherently risky. These risks come from multiple directions, including:

• Honest mistakes - An agent can simply make a mistake that results in data loss, corruption, or unintended side effects. It's very easy to find stories of Claude wiping out entire directories or otherwise causing havoc.
• Prompt injection - Agents that are exposed to the outside world (e.g. by downloading untrusted web content) can potentially be manipulated into doing things outside of their operator's intent or control.
• Supply chain attacks - Agents may download and run compromised software or dependencies from external sources, which could introduce malicious code into the environment, at build time, runtime, or both.
• Rogue agents - The agent itself could behave maliciously due to a compromise of the model, the provider, or emergent behavior.

While these are already in play to some extent, increasing AI capabilities guarantee that attacks will become increasingly frequent and sophisticated. Supply chain attacks in particular have become a near-constant backdrop: the XZ Utils backdoor (a multi-year social engineering campaign against a burned-out maintainer, caught by luck in 2024), the Shai-Hulud self-replicating npm worm (500+ packages compromised in September 2025, escalating to 25,000+ repositories as "Shai-Hulud 2.0" in November 2025), and the TeamPCP campaign (compromising litellm, telnyx, and the widely-used axios npm package in March 2026) are just a few recent examples. North Korean threat actors alone have pushed 1,700+ malicious packages across npm, PyPI, Go, and Rust. The registries that developers (and their agents) depend on are under active, sustained attack.

All of these suggest similar solutions, though. You need strong guardrails (isolation, permissions, etc.) to ensure that when things go sideways, the blast radius is contained and the operator retains control.

Workload Management

Anyone who has had more than one or two parallel agentic sessions has likely run into the problem of keeping track of which agents are doing what, which sessions are active, how to coordinate work across multiple agents (possibly working in the same repository or worktree), how to keep them all running reliably (e.g. even when you close your laptop or lose your network connection), etc.

These are real challenges that impose real limits on how many agentic workloads a single operator can reasonably manage at once. Most devs who have leaned into this space have developed some amount of custom tooling to help with this problem. Solving for this at the platform layer should be a significant enabler to delivering value more quickly.

Consistency

Similar to workload management, inconsistency across workload environments (different tools, configuration, files, etc.) creates significant friction and potential for errors when trying to scale up agentic engineering.

While sometimes these differences are intentional and should be preserved (e.g. wanting Agent A to have different tools and permissions than Agent B), they often are accidental and introduce unnecessary complexity and risk.

Control

The operator should retain control over what agents are doing, how workloads are executed, and what resources they can access even as those workloads become more autonomous. This is a central design goal of Agentworks, and it ties the preceding concerns together: without reliable knowledge of what agents are doing, consistent environments, and contained blast radius, control is lost in practice even if it's notionally retained.

A significant and growing part of the ecosystem treats loss of control as an inevitable cost of agentic autonomy. Agentworks takes the opposite position: autonomy and control are not mutually exclusive. A good platform should make it possible and straightforward to have both.

Core Concepts

Agentworks organizes work into five core concepts:

The Operator - the Person in Control

Agentworks is currently designed around a single human "operator" who is in control of all agentic workloads. The operator is responsible for creating VMs, workspaces, agents, and sessions, and for orchestrating how these components interact.

Note that while you might find some exceptions, we generally reserve the term "user" for the technical Linux users that exist on the VMs (the admin user and the agentic identities).

VMs - the Compute Environment

VMs define the base compute environment for all workloads. As discussed in ADR 0001, Agentworks uses VMs as the fundamental unit of compute to provide for strong isolation while providing all the capabilities of a full Linux environment (full daemonized services, multi-user, ability to run containers, etc.).

VMs further use a single operating system (Debian Bookworm, see ADR 0002) to ensure consistency and minimize VM management complexity and risk.

VMs are generally intended to be long-lived and are designed to support any number of agentic workloads. A robust configuration and templating mechanism is provided so that VM provisioning can be automated and standardized across environments. VMs can further be "reinitialized" to declaratively update them based on changes to the template or configuration.

Each VM also includes an "admin" user that has full sudo privileges that is used for all provisioning and management tasks on the VM. While not recommended, the admin user is also available for agentic workloads if the operator so desires.

Workspaces - the Project

A workspace defines the project scope. Workspaces ultimately consist of a root directory that can be based on a git repository or an empty directory. The workspace also maps to a Linux group with workspace permissions and ACLs set to allow collaborative access to the files within the workspace for all members of the group. Workspace-level configuration (e.g. Claude Code's project settings) can be used to control how tools behave within the context of this workspace.

The Agentworks workspace mechanism fully supports any number of workspaces mapping to the same underlying repository. To simplify administration, each is a full independent clone.

While VM workspaces are the primary supported workspace type, local workspaces can also be created on the operator's workstation. Local workspaces do not support agents because the isolation model that underpins agent execution requires Linux user management that is only available on VMs.

Agents - the Actor

An agent defines a security identity on a VM. Each agent maps to its own full Linux user, capable of having its own processes, private files, shell environment, etc. This allows for the creation of different identities with different privileges and capabilities.

Agents are mapped to workspaces, either explicitly via grants or implicitly via sessions (see below). This mapping drives standard group and filesystem permissions that control what agents are able to access.

Agents are only supported on VM workspaces because the isolation model requires Linux user management (useradd, group membership).

Sessions - the Workloads

A session is the primary way of running interactive workloads in Agentworks (e.g. a Claude Code instance). It provides the mechanism by which an agent can execute commands within the context of a workspace. A unique name and a persistent tmux session allow the operator to have any number of concurrent workloads running across their VMs, workspaces, and agents. Agentworks allows the operator to attach to and detach from them as needed to monitor progress or interact with the workload, and then to stop, restart, and delete them to manage their lifecycle.

Key Principles

Opinionated Consistency

Broadly-applicable systems like Agentworks can easily spiral into significant complexity by attempting to support too many ways of doing the same thing. To protect against this, Agentworks takes an opinionated stance on how things should be set up. A single base operating system, tightly-integrated tooling, and emphasis on declarative configuration all help minimize variation and surprises across different workloads.

Composable Isolation

This model provides several isolation mechanisms, which operators can compose to achieve their desired security posture. While the system is optimized around the full isolation model (VMs, agents, and workspaces), this is by no means required. Operators are free to use any subset that makes sense for their security and operational requirements.

Ephemerality

The layers differ in intended lifespan. VMs are intended to be long-lived: provisioned once and used across many projects. Workspaces are intended to be medium-lived: created to support a particular workstream or project and destroyed when done. Agents can be long-lived or short-lived depending on the operator's preferences. Long-lived agents can be reused across multiple workspaces and sessions or they can be created for a single workspace or session and destroyed when no longer needed. Sessions are intended to be the most ephemeral: started for a specific activity and discarded when done.

Declarative Configuration and Templates

Each layer has a templating mechanism using declarative configuration so that patterns can be defined once and stamped many times. The longer-lived resources (VMs and agents) provide for mostly idempotent "reinitialization" so that they can be reliably evolved over time.

Tightly Integrated Tools

In the spirit of opinionated consistency, Agentworks tightly integrates a small set of excellent tools that add significant value. While these tools could theoretically be replaced with alternatives, this would involve significant additional complexity that would slow down development and increase the likelihood of inconsistencies or errors.

Those using Agentworks are highly encouraged to embrace these tools rather than attempting to work around them.

SSH

SSH is the control plane for all VM operations. Agentworks uses SSH to provision VMs, initialize them, manage agents, run sessions, transfer files, and execute commands. The operator's SSH key (configured in [operator]) is deployed to VMs during provisioning and is the sole authentication mechanism for all subsequent operations.

During provisioning, SSH access uses the platform's native transport (Lima shell, Azure public IP, WSL2 exec, or Proxmox guest agent). Once Tailscale is joined (see below), all further SSH access goes over the tailnet. Agentworks automatically manages ~/.ssh/config entries for each VM so that standard SSH tools (scp, ssh, VS Code Remote) work seamlessly.

Tailscale

VMs join a Tailscale tailnet during provisioning. All subsequent SSH access (workspace shell, VM shell, initialization) goes over Tailscale, providing secure connectivity without exposing SSH ports to the public internet.

During vm create (and vm start when re-joining), you will be prompted for a Tailscale auth key unless the TAILSCALE_AUTH_KEY environment variable is set. Generate keys at the Tailscale admin console.

Ephemeral auth keys (with ?ephemeral=true appended) are fully supported. The Tailscale node is automatically removed from the tailnet when the VM goes offline. Agentworks handles re-joining gracefully on vm start by prompting for a new auth key (or using TAILSCALE_AUTH_KEY).

Tmux

Sessions are built on tmux, which provides persistent terminal sessions that survive disconnects and support attach/detach. Each session maps 1:1 to a tmux session on the VM.

Agentworks provides two console layers for interacting with sessions:

• Workspace console (workspace console): a tmuxinator-managed tmux session with one window per session in the workspace, plus an admin shell. This is the recommended way to interact with sessions.
• VM console (vm console): a dynamically-built tmux session spanning all workspaces on the VM.

Agent-mode sessions run on per-agent tmux sockets for proper process isolation and terminal resize propagation. See the tmux Architecture section for details.

Additional Tools

A few other tools, while not fundamental, warrant a brief mention:

• Git is fully integrated into workspace configuration, allowing operators to define workspace templates around specific repositories. Integrated git credential management makes it easy to use different providers (GitHub, Azure DevOps, etc.) with any number of scoped credentials (e.g. access tokens) to control capabilities and blast radius.
• VS Code Workspaces are automatically generated (using the Remote - SSH extension) for each workspace Agentworks manages, allowing developers to easily open an Agentworks workspace directly in VS Code to view files, use the terminal, and leverage the full VS Code feature set.
• Mise en Place is supported out of the box for easily adding tools, including checksum validation using lockfiles where supported by the backend.
• Dotfiles can be configured for both the admin user and agents, helping to ensure a consistent terminal environment (shell configuration, editor settings, etc.) across workloads.

Getting Started

uv sync
uv run agentworks config init    # creates ~/.config/agentworks/config.toml

Edit the config file (at minimum, set your SSH key paths), then:

agentworks vm create          # provision + initialize a VM
agentworks workspace create   # create a workspace on the VM
agentworks workspace shell my-workspace

Prerequisites

• Python 3.12+
• uv package manager
• Tailscale installed and connected (for VM workspaces)
• One of: Lima, Azure CLI (az), or WSL2 (for VM provisioning)

Global Options

Flag	Description
--non-interactive	Disable all interactive prompts

When --non-interactive is set (or stdin is not a TTY), commands that would normally prompt for missing values (VM selection, workspace selection, name generation) will fail with a clear error indicating which flag is required. Auto-selection still works: if there is exactly one VM or workspace, it is used without prompting.

Commands

Top-level

Command	Description
agentworks doctor	Check environment and config
agentworks completion zsh	Output zsh completion script

VM Hosts

Manage machines that host VMs (for remote Lima mode).

Command	Description
agentworks vm-host add <name> <ssh-host>	Register a VM host
agentworks vm-host list	List registered VM hosts
agentworks vm-host remove <name>	Remove a VM host

VMs

Manage virtual machines across Lima (local or remote), Azure, and WSL2.

Command	Description
agentworks vm create	Create a new VM (provision + initialize)
agentworks vm list	List VMs with status and resources
agentworks vm describe <name>	Show VM details, workspaces, and event log
agentworks vm shell <name>	SSH into a VM's home directory
agentworks vm start <name>	Start a stopped VM
agentworks vm stop <name>	Stop a running VM
agentworks vm reinit <name>	Re-run initialization on a provisioned VM
agentworks vm delete <name>	Delete a VM (with confirmation)
agentworks vm logs <name>	Show SSH logs for a VM
agentworks vm console <name>	Attach to the VM console
agentworks vm add-git-credential <name> <cred>	Add or update a git credential

vm create accepts --name, --platform, --vm-host, --admin-username, --cpus, --memory, --disk, and --azure-vm-size. These are immutable provisioning parameters stored in the database. All initialization behavior (packages, install commands, etc.) is driven by config.

vm reinit re-runs the initialization phase using the current config without reprovisioning the VM. Changes to config (new packages, different install commands, etc.) are picked up automatically.

vm delete requires --force if the VM has workspaces, agents, or sessions. The confirmation message shows what will be deleted. Pass --yes to skip the prompt.

Workspaces

Manage workspaces on VMs or locally.

Command	Description
agentworks workspace create	Create a workspace (VM or --local)
agentworks workspace describe <name>	Show workspace details and sessions
agentworks workspace shell <name>	Open a plain shell into a workspace
agentworks workspace console <name>	Open the workspace console (tmux)
agentworks workspace list	List workspaces
agentworks workspace copy <source>	Copy a workspace to a new location
agentworks workspace rehome <name>	Move workspace to a new path
agentworks workspace repair <name>	Repair workspace infrastructure
agentworks workspace delete <name>	Delete a workspace

workspace create accepts --name, --vm, --local, --template, and --open-vscode.

workspace console opens a tmuxinator session (ws-<name>-console) with an admin-shell window plus one window per session in the workspace. Pass --recreate to kill and rebuild the console. This is the recommended way to interact with sessions from within VS Code or any terminal on the VM.

workspace copy copies a workspace to a new location. Accepts --name, --vm, and --local (same pattern as workspace create). Works across VMs, VM to local, and local to VM.

workspace delete requires --force if the workspace has sessions. Running sessions are killed during deletion. Pass --yes to skip the confirmation prompt.

Agents

Manage agents (isolated Linux users) on VMs. Agents are VM-scoped and access workspaces via grants.

Command	Description
agentworks agent create [--name] [--vm]	Create an agent on a VM
agentworks agent list [--vm <vm>]	List agents
agentworks agent describe <name>	Show agent details and grants
agentworks agent reinit <name>	Re-run agent setup
agentworks agent workspace-grants grant <name> <ws>[,<ws>]	Grant workspace access
agentworks agent workspace-grants grant <name> --all	Grant access to all workspaces
agentworks agent workspace-grants deny <name> <ws>[,<ws>]	Remove workspace access
agentworks agent workspace-grants deny <name> --all	Remove all explicit grants
agentworks agent workspace-grants list <name>	List workspace grants
agentworks agent shell <name> [--workspace <ws>]	Shell into an agent
agentworks agent delete <name>	Delete an agent

agent create accepts --name, --vm, --template, and --grant-all-workspaces.

agent delete requires --force if the agent has running sessions. Pass --yes to skip the confirmation prompt.

Sessions

Manage sessions (persistent tmux sessions running in workspaces). Session names are globally unique -- no --workspace flag needed for most commands.

Command	Description
agentworks session create	Create and start a session
agentworks session describe <name>	Show session details
agentworks session list [--workspace <ws>]	List sessions with status
agentworks session attach <name>	Attach to a running session
agentworks session stop <name>	Stop a running session
agentworks session restart <name>	Restart a session
agentworks session delete <name>	Stop and delete a session
agentworks session logs <name>	Dump session scrollback buffer
agentworks vm console <vm-name>	Attach to the VM console

session create accepts --name, --workspace, --template, --admin, and --agent. Workspace, mode (admin vs agent), and name are prompted interactively if omitted. If agents exist on the VM and neither --admin nor --agent is specified, you are prompted to choose. Pass --new-workspace to create a workspace on the fly (with optional --workspace-name, --workspace-template, and --vm). When a session created with --new-workspace is later deleted, you are offered the option to delete the workspace as well (if no other sessions remain).

tmux Architecture

Each session runs in its own locked-down tmux session on the VM. There are three ways to interact with sessions, at different scopes:

Method	Scope	tmux session name	Entry point
session attach	One session	<session-name>	Operator's machine
workspace console	One workspace	ws-<workspace>-console	On-VM or operator's machine
vm console	All workspaces	vm-console	Operator's machine

Session tmux sessions

Each session gets a locked-down tmux session using the session name directly as the tmux session name. The user's ~/.tmux.conf (customizable via dotfiles) is loaded first so that familiar keybindings (prefix, detach, copy mode, scroll) work for direct session attach. Window/pane creation, session management, and the command prompt are selectively unbound.

Agent-mode sessions run on a per-agent tmux socket so the agent's shell connects directly to the tmux pane PTY. The socket path is persisted in the database.

Workspace console

workspace console uses tmuxinator to create or attach to a ws-<name>-console session. The tmuxinator config (.tmuxinator.yml in the workspace root) is regenerated whenever sessions change, so the console always reflects the current set of sessions. This is the recommended way to interact with sessions from within VS Code or any terminal on the VM.

ws-myproject-console (tmuxinator, full tmux)
  Window 1: admin-shell                login shell for the admin user
  Window 2: myproject-claude           attached to session
  Window 3: myproject-debug            attached to session

VM console

vm console creates or attaches to the vm-console session, which spans all workspaces on the VM. This is built dynamically (not via tmuxinator) and is managed from the operator's machine.

Shells

workspace shell and vm shell open plain login shells with no tmux. Use these when you just need a terminal without the console structure.

Key behaviors

• Direct attach (session attach): the user's prefix key, detach, copy mode, and scroll all work normally. Status bar is hidden since there is only one pane.
• Consoles (workspace console, vm console): the console's prefix key eclipses the inner session's prefix, so window switching, detach, etc. all operate at the console level. Session windows use a wrapper that re-attaches if the inner session disconnects and shows a message when the session ends.
• Nesting protection: both console commands refuse to run inside an existing tmux session to avoid prefix key conflicts. Pass --allow-nesting to override.
• Console lifecycle: consoles are independent of sessions. Killing or detaching a console does not affect running sessions. --recreate rebuilds from scratch.

Session Templates

Templates define the command a session runs. The built-in default template runs a login shell ($SHELL --login), respecting whatever shell the user (admin or agent) is configured with. Define custom templates in config:

[session_templates.default]            # override the built-in default
command = "claude --name {{session_name}}"
restart_command = "claude --resume {{session_name}}"
description = "Claude Code interactive session"

Template commands support {{session_name}} and {{workspace_name}} variable substitution (double-brace syntax, consistent with nerftools manifests). The optional restart_command is used by session restart -- useful for tools like Claude Code where --resume picks up the previous conversation. If omitted, the regular command is used.

Installers

Browse and inspect the built-in catalog of installable tools.

Command	Description
agentworks installer list	List all available catalog entries
agentworks installer describe <name>	Show details of a catalog entry

installer list accepts --type (apt-source, apt-package, system-install-cmd, user-install-cmd) and --source (builtin, user) filters.

Config

Command	Description
agentworks config init	Create a sample config file
agentworks config edit	Open config in $EDITOR
agentworks config sample	Print the sample config to stdout
agentworks config sync-ssh-config	Rebuild SSH config entries for all VMs
agentworks config sync-vscode-workspaces	Regenerate .code-workspace files for all VMs

Configuration

Config lives at ~/.config/agentworks/config.toml. Run agentworks config init to generate a sample with all options documented. See sample-config.toml for the full reference.

Key sections:

• [operator] -- SSH keys (required), additional authorized keys, SSH config management
• [paths] -- local workspace, VM workspace, and VS Code workspace file directories
• [defaults] -- default platform, VM host
• [vm_templates.*] -- VM resources, apt packages, system install commands, mise
• [admin.config] -- admin user shell, dotfiles, git credentials, user install commands, mise
• [agent_templates.*] -- agent user shell, dotfiles, git credentials, user install commands, mise
• [session.config] -- session defaults (history limit)
• [session_templates.*] -- session templates with variable substitution
• [workspace_templates.*] -- workspace templates with inheritance
• [git_credentials.*] -- git credential providers (GitHub, Azure DevOps)
• [apt_sources.*] -- user-defined third-party apt repositories
• [apt_packages.*] -- user-defined named apt package sets
• [system_install_commands.*] -- user-defined system-level install commands
• [user_install_commands.*] -- user-defined per-user install commands
• [azure] -- Azure-specific settings
• [proxmox] -- Proxmox VE API settings

Mise (Polyglot Tool Manager)

Agentworks installs mise by default on all VMs for managing CLI tools (terraform, adr-tools, node, etc.) with optional lockfile-based integrity verification. See Using mise for the full guide.

Nerf Tools (Claude Code Plugin)

Agentworks can build and deploy a Claude Code plugin containing "nerf tools" -- scoped, safety-constrained wrappers for CLI operations like git, az, and other tools. Nerf tools enforce guardrails (validated parameters, restricted flags, pre-flight checks) so AI agents operate safely.

Enable in your VM template:

[vm_templates.default]
nerf_build_claude_plugin = true

This builds the plugin to nerf_home_dir/claude-plugin/ during VM init. To auto-install the plugin for users, add to admin or agent config:

[admin.config]
nerf_install_claude_plugin = true

The plugin provides skills that document available tools, and operator commands for managing permissions (/nerftools:nerfctl-grant-allow, /nerftools:nerfctl-grant-deny, etc.). Custom tool manifests can be added via nerf_addl_manifests.

Plugin identity (name, marketplace metadata) is defined in agentworks' own nerf-config.yaml and loaded via the nerftools config API. The version is a date-based build stamp that changes on each reinit. The build always emits an embedded marketplace so the plugin directory is installable standalone via claude plugin marketplace add.

Built-in Catalog

Agentworks ships a built-in catalog of common tools (apt sources, apt packages, system install commands, and user install commands). Run agentworks installer list to see what is available. Reference catalog entries by name in vm_templates, admin.config, and agent_templates. User-defined entries in your config override built-in entries with the same name.

VM Initialization

VM creation follows a two-phase lifecycle tracked by separate status columns:

1. Provisioning (provisioning_status) -- one-time, platform-specific, over the provisioning transport (Lima shell, SSH, or WSL2 exec): create user, install system packages, add SSH key, install and join Tailscale

2. Initialization (init_status) -- repeatable via vm reinit, over Tailscale SSH: configure apt sources, install apt packages, install snap packages, install mise, set shell, reconcile SSH authorized keys, run system install commands, write mise config, configure PATH, configure git credentials, sync dotfiles, fetch mise lockfile, run mise install, run user install commands for the admin user

Initialization is fully declarative -- driven entirely by config. vm create only accepts immutable provisioning parameters (name, platform, resources). vm reinit takes only the VM name and re-runs initialization using the current config.

Non-fatal initialization failures (packages, dotfiles) produce a partial status rather than aborting. Fatal failures prompt for deletion or reinit. Use vm describe to view the full event log.

Shell Completion

mkdir -p ~/.zfunc
agentworks completion zsh > ~/.zfunc/_agentworks

Add to .zshrc:

fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit

Completions include dynamic VM, workspace, VM host, session, and template name lookups.

State

All state is stored in ~/.config/agentworks/agentworks.db (SQLite). Schema migrations are forward-only and run automatically.

Environment Variables

Variable	Description
TAILSCALE_AUTH_KEY	Tailscale auth key (skips prompt)
GIT_CREDENTIALS_<CRED_NAME>	Git credential for <CRED_NAME> (skips prompt)