gricha/perry

Perry Usage

Perry runs a local agent that creates isolated Docker workspaces and advertises them on your tailnet. Each workspace has coding agents preinstalled and is reachable via CLI, web UI, or SSH.

Quick start

# Install
curl -fsSL https://raw.githubusercontent.com/gricha/perry/main/install.sh | bash

# Run the agent
perry agent run

# Point your CLI at the agent (one-time)
perry config agent <hostname>

# Create a workspace (optional clone)
perry start my-proj --clone [email protected]:user/repo.git

# Shell into it
perry shell my-proj

Expected behavior:

• perry agent run starts a local daemon.
• perry start creates a workspace-my-proj container and registers it on your tailnet.
• perry shell opens an interactive shell inside the workspace.

OpenCode workflow

# Attach via CLI
opencode attach http://my-proj:4096

Expected behavior:

• OpenCode is reachable at http://<workspace>:4096 from any device on the tailnet.
• You can open the same URL in a browser.

Gotchas:

• If :4096 is unreachable, verify tailnet connectivity and that the workspace is running.

Claude Code workflow

# Run from a workspace shell
perry shell my-proj
claude

Expected behavior:

• Claude Code runs inside the workspace shell.
• Remote access to the workspace shell can be done via Perry web UI or a mobile terminal app.

Gotchas:

• You do not attach to Claude Code over HTTP; use it inside the workspace shell.

SSH access

ssh workspace@my-proj

Expected behavior:

• The username is workspace and the hostname is the workspace name (e.g., my-proj).
• The workspace inherits authorized keys from the host.
• If your key works on the host, it should work on the workspace.

Gotchas:

• The SSH username is workspace, not part of the hostname. Use ssh workspace@<name>, not ssh workspace-<name>.
• If SSH fails, ensure your host keys exist and the workspace is on the tailnet.

Common commands

# List workspaces
perry list

# Stop a workspace
perry stop my-proj

# Remove a workspace
perry remove my-proj

Troubleshooting

• Workspace not reachable: confirm Tailscale is running and the workspace name resolves.
• Port conflicts: if you changed ports, update your attach URL.
• Slow start: workspace setup can take time; check the web UI for startup progress.

Naming conventions

• Containers are workspace-<name>.
• Internal resources use workspace-internal-<name>.

References

• Getting Started: https://gricha.github.io/perry/docs/getting-started
• OpenCode workflow: https://gricha.github.io/perry/docs/workflows/opencode
• Claude Code workflow: https://gricha.github.io/perry/docs/workflows/claude-code