mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-10-02 13:39:41 +02:00
DevvynandClaude Opus 5.5
5cf5a45438
Add Case -> Clone Repo could only reach public repositories in the Docker deployment. This lets a deployment opt in to the GitHub CLI and the Azure CLI (+ azure-devops extension) as git credential helpers. Codeman itself still collects no credentials. - server.Dockerfile / agent.Dockerfile: CODEMAN_INSTALL_GH / CODEMAN_INSTALL_AZ build args (0 or 1, default 0; anything else stops the build). Off leaves no apt repository, package, extension, helper script or credential entry, so a default build is unchanged. On installs from the vendors' apt repositories and configures system gitconfig helpers: github.com / gist.github.com -> `gh auth git-credential`, dev.azure.com / *.visualstudio.com -> new docker/git-credential-azure-cli (an Entra ID token from `az account get-access-token`, or AZURE_DEVOPS_EXT_PAT). A helper whose CLI is not signed in prints nothing, so a private clone still fails fast. - The extension lives in AZURE_EXTENSION_DIR outside HOME (/opt/codeman-az-extensions, runtime-owned; /opt/az-extensions, gid-0 group-writable in the agent image). - Hosts turn them on in docker-compose.override.yml: `build: args:` for the server image, `environment:` CODEMAN_AGENT_IMAGE_INSTALL_GH / _AZ for the agent image. build-agent-image.mjs and the in-app auto-build share one env -> ARG table (pinned by the parity test) and pass nothing when unset. docker-compose.yaml is untouched; .env.example only gains a comment, so the self-updater's environment gate sees no new keys. - Docker cases seed the gh sign-in (~/.config/gh/hosts.yml, config.yml) and the az sign-in files from ~/.azure per file, read-only, like pi/grok. - The Clone Repo AUTH_REQUIRED message says how to sign the server's git in instead of claiming private repositories cannot be cloned. - Docs: docker/README.md "Private repositories", docker-compose.md, docker-cases.md, the Quick-Start / Core-Concepts / Docker-Cases wiki pages, security-architecture.md, architecture-invariants.md, changeset. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0167CiuzLrmjYWxwKp3rMWjw
157 lines
8.2 KiB
Markdown
157 lines
8.2 KiB
Markdown
# Quick Start
|
|
|
|
From an installed Codeman to a working agent, in about five minutes. If you have not
|
|
installed yet, start at [Installation](Installation).
|
|
|
|
## 1. Start the server
|
|
|
|
```bash
|
|
codeman web
|
|
```
|
|
|
|
It prints a URL, `http://localhost:3000` by default. Open it.
|
|
|
|
The server binds `127.0.0.1` only, so this URL works from the machine running it and
|
|
nowhere else. That is deliberate: Codeman starts agents with permission prompts skipped by
|
|
default, so anyone who can reach the dashboard can run code on this machine. Reaching it
|
|
from your phone is a separate, deliberate step covered in [Remote Access](Remote-Access).
|
|
|
|
To keep it alive after you close the terminal, use `codeman web -d` instead, or install it
|
|
as a service. See [Running As A Service](Running-As-A-Service).
|
|
|
|
## 2. Meet the welcome screen
|
|
|
|
With no sessions running you get the welcome screen:
|
|
|
|
- **Run buttons** for each agent CLI Codeman found on your PATH. If you expected one and it
|
|
is missing, its binary is not visible to the server; see [Agent CLIs](Agent-CLIs).
|
|
- **A QR code**, if a password is set. Scanning it logs a phone in without typing anything.
|
|
- **Resume Conversation**, a list of past sessions, including Claude conversations started
|
|
outside Codeman. Empty on a fresh install.
|
|
- **Search**, across sessions, events, and files.
|
|
|
|
You can click a Run button right now and get a working agent in your current case. The rest
|
|
of this page is the deliberate version.
|
|
|
|
## 3. Pick or create a case
|
|
|
|
A **case** is a named working directory that Codeman remembers. Every session runs inside
|
|
one. The case picker is in the bottom toolbar.
|
|
|
|
To make a new one, click **+** next to the picker. The Add Case dialog has three tabs:
|
|
|
|
| Tab | Use it when |
|
|
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
|
|
| **Create New** | Starting a fresh project. Creates `~/codeman-cases/<name>` and scaffolds a `CLAUDE.md` into it. |
|
|
| **Clone Repo** | Working on an existing repo: public, or private once this machine's git can authenticate (the Docker image can include `gh`/`az` helpers for this). Paste the URL; Codeman preflights it as you type, offers the repo's real branches and tags, and fills in the case name. |
|
|
| **Link Existing** | The code is already on disk. Point at the folder, with **Browse** if you would rather click than type. |
|
|
|
|
The gear next to the picker holds two per-case toggles: **Agent Teams** and
|
|
**1M Opus Context**. Both are off by default and both are safe to ignore for now.
|
|
|
|
**Create New** also has a checkbox for running the case inside a Docker container, and a
|
|
**Remote** panel for running it over SSH on another machine. Those are
|
|
[Docker Cases](Docker-Cases) and [Remote SSH Sessions](Remote-SSH-Sessions); skip them for
|
|
your first session.
|
|
|
|
## 4. Pick a run mode and hit Run
|
|
|
|
The **Run** button starts an agent in the selected case. The arrow next to it picks which
|
|
one:
|
|
|
|
| Mode | What starts |
|
|
| -------------------- | -------------------------------------------------------------- |
|
|
| **Claude Code** | The default, and the mode every Codeman feature supports. |
|
|
| **OpenCode** | |
|
|
| **Codex** | OpenAI's CLI. |
|
|
| **Gemini** | Enterprise only since Google's consumer cutover. |
|
|
| **Antigravity** | Google's successor to the consumer Gemini CLI. |
|
|
| **Pi** | No permission prompts and no sandbox by design. |
|
|
| **Grok Build** | xAI's CLI. |
|
|
| **DeepSeek Harness** | Needs a terminal profile; the menu offers to install one. |
|
|
| **OMP** | Oh My Pi, configured entirely through its own `~/.omp`. |
|
|
| **Terminal / Shell** | A plain shell, no agent. Also the **Run Shell** button. |
|
|
|
|
The dropdown also lists any saved dashboard URLs ([Web Tabs](Web-Tabs)) and your recent
|
|
sessions. Those do not change the run mode: Run always means "start an agent".
|
|
|
|
Click **Run**. A tab appears, and Codeman spawns the CLI on a real PTY inside a tmux
|
|
session and streams it to your browser.
|
|
|
|
The number spinner beside the button starts several sessions at once, up to 20. Useful for
|
|
fanning the same case out across parallel workers; unnecessary for a first run.
|
|
|
|
## 5. Talk to the agent
|
|
|
|
Click into the terminal and type. It is a real terminal (xterm.js over a real PTY), so full
|
|
TUIs render properly and everything the CLI supports works, slash commands included.
|
|
|
|
| Key | Effect |
|
|
| ---------------------------- | --------------------------------------------- |
|
|
| `Enter` | Send. |
|
|
| `Shift+Enter` / `Ctrl+Enter` | Newline without sending. |
|
|
| `Ctrl+C` | Copy if text is selected, otherwise interrupt. |
|
|
| `Ctrl+Shift+V` | Voice input. |
|
|
|
|
You can also paste or drag an image straight into the session, and register external files
|
|
as attachments. See [Working With Files](Working-With-Files) and
|
|
[Input And Voice](Input-And-Voice).
|
|
|
|
Input is delivered **exactly once**, even if your connection drops mid-prompt. A dropped
|
|
link never loses a prompt and never sends it twice.
|
|
|
|
## 6. Read the tab
|
|
|
|
The tab tells you what the session is doing without opening it:
|
|
|
|
| Signal | Meaning |
|
|
| --------------------- | ---------------------------------------------------------- |
|
|
| Green dot | Alive and idle. |
|
|
| Pulsing green dot | Working on a turn. |
|
|
| Yellow, blinking | Waiting for you to type something. |
|
|
| Red, blinking | A question or permission prompt is blocking the agent. |
|
|
|
|
Full tour in [The Dashboard](The-Dashboard). If you want a phone notification when an agent
|
|
needs you, that is [Notifications And Approvals](Notifications-And-Approvals).
|
|
|
|
## 7. Leave, and come back
|
|
|
|
Close the browser tab. Close the laptop. The agent keeps running, because it lives in tmux
|
|
and not in your browser.
|
|
|
|
Reopen the dashboard and the session is still there with its scrollback intact. First load
|
|
of a session pulls the full tmux scrollback, so you get the history, not just what arrived
|
|
after you reconnected.
|
|
|
|
This also survives restarting the Codeman server itself. What does not survive is killing
|
|
the tmux server or rebooting the machine.
|
|
|
|
## 8. Stop things
|
|
|
|
| To do this | Do that |
|
|
| ------------------------- | ------------------------------------------------------------------- |
|
|
| Interrupt the current turn | `Ctrl+C` with nothing selected, or the **Stop** button. |
|
|
| Close one session | `Ctrl+W`, or the tab's close control. |
|
|
| Stop the server, keep agents | `codeman web --stop`. The tmux sessions stay alive. |
|
|
| Stop everything | `tmux -L codeman kill-server`. |
|
|
|
|
If you are working *inside* a Codeman-managed session (`echo $CODEMAN_MUX` prints `1`),
|
|
never run `tmux kill-session` or `pkill claude` by hand. You will kill the session you are
|
|
sitting in, along with its siblings.
|
|
|
|
## Where to go next
|
|
|
|
**Make it run without you.** [Keeping Agents Running](Keeping-Agents-Running) covers idle
|
|
detection, respawn cycling, and auto-resume when a subscription limit resets. That is the
|
|
feature Codeman exists for.
|
|
|
|
**Get it on your phone.** [Remote Access](Remote-Access), then
|
|
[Mobile Guide](Mobile-Guide).
|
|
|
|
**Understand what you just used.** [Core Concepts](Core-Concepts) explains cases, sessions,
|
|
run modes, and what state lives where.
|
|
|
|
**Automate it.** [Cron Jobs](Cron-Jobs) for scheduled work,
|
|
[Driving Codeman From An Agent](Driving-Codeman-From-An-Agent) for agents that spawn and
|
|
supervise other agents.
|