@wnzzer/agentdock 0.1.11 → 0.1.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +148 -162
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -1,230 +1,216 @@
|
|
|
1
|
-
# AgentDock
|
|
1
|
+
# AgentDock ⚓ — One canvas for your coding agents
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<p align="center">
|
|
4
|
+
<picture>
|
|
5
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-dark.svg">
|
|
6
|
+
<img src="docs/assets/banner-light.svg" alt="AgentDock — one canvas for the official Claude Code and Codex CLIs, on your own machine.">
|
|
7
|
+
</picture>
|
|
8
|
+
</p>
|
|
4
9
|
|
|
5
|
-
|
|
10
|
+
<p align="center">
|
|
11
|
+
<a href="https://github.com/wnzzer/agentdock/actions/workflows/check.yml"><img src="https://github.com/wnzzer/agentdock/actions/workflows/check.yml/badge.svg" alt="CI status"></a>
|
|
12
|
+
<a href="https://www.npmjs.com/package/@wnzzer/agentdock"><img src="https://img.shields.io/npm/v/%40wnzzer%2Fagentdock?style=flat-square&label=npm&color=0c8376" alt="npm version"></a>
|
|
13
|
+
<img src="https://img.shields.io/badge/node-%E2%89%A5%2024-0c8376?style=flat-square" alt="Node.js 24 or newer">
|
|
14
|
+
<img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-7760b5?style=flat-square" alt="Platforms: macOS and Linux">
|
|
15
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License: MIT"></a>
|
|
16
|
+
</p>
|
|
6
17
|
|
|
7
|
-
|
|
8
|
-
npm i -g @wnzzer/agentdock # or: npx @wnzzer/agentdock
|
|
9
|
-
agentdock # starts in the background and prints its URL
|
|
10
|
-
```
|
|
18
|
+
<p align="center"><b>English</b> · <a href="README.zh-CN.md">简体中文</a></p>
|
|
11
19
|
|
|
12
|
-
|
|
13
|
-
server actually answers, and returns to the shell. `agentdock stop`, `restart`,
|
|
14
|
-
`status` and `logs` manage it; `agentdock serve` runs in the foreground instead,
|
|
15
|
-
which is what a supervisor such as systemd should use. A failed start prints the
|
|
16
|
-
reason from the log and exits non-zero rather than leaving a silent process.
|
|
20
|
+
AgentDock is a self-hosted web workspace for the **official Claude Code and Codex clients**. It runs on the machine where your code lives — a laptop, a dev box, a server behind SSH — and gives every agent session, file, diff and terminal a place on one recursive split/tab canvas you can open from any browser. Rust server, Vue 3 client, one binary, no Docker.
|
|
17
21
|
|
|
18
|
-
|
|
22
|
+
**A dock, not another agent.** AgentDock never implements an agent loop, a tool executor or a permission system of its own. Codex is driven through its official `app-server`; Claude Code through the CLI's own `stream-json` control interface. Your logins, models, hooks and permission prompts stay native — AgentDock renders an approval as a card and forwards your decision, and it never answers one for you or reads a client's credentials. When the official clients gain a feature, it arrives through the adapter rather than a reimplementation. The reasoning is in [Product boundary](docs/product-boundary.md).
|
|
19
23
|
|
|
20
|
-
|
|
24
|
+
[Install](#install) · [Quick start](#quick-start) · [Highlights](#highlights) · [How it fits together](#how-it-fits-together) · [Security](#security) · [Docs](#documentation) · [Releases](https://github.com/wnzzer/agentdock/releases)
|
|
21
25
|
|
|
22
|
-
Tarballs with a `SHA256SUMS` are attached to each [release](https://github.com/wnzzer/agentdock/releases) for installing without npm.
|
|
23
26
|
|
|
24
|
-
|
|
27
|
+
<p align="center">
|
|
28
|
+
<img src="docs/assets/screenshot-canvas.png" alt="The AgentDock canvas: a rendered Markdown file, the Git changes pane and a Rust source file docked side by side, with the file explorer on the right." width="100%">
|
|
29
|
+
<br><sub>The shared canvas — files, Git and code docked side by side. A real session against this repository.</sub>
|
|
30
|
+
</p>
|
|
25
31
|
|
|
26
|
-
|
|
32
|
+
<p align="center">
|
|
33
|
+
<img src="docs/assets/screenshot-chat.png" alt="The structured conversation view: folding tool cards, a native approval card and the composer with a context ring." width="100%">
|
|
34
|
+
<br><sub>Structured conversations: folding tool cards and native approval cards. Rendered by the built-in read-only design lab from local fixtures — no client or model involved.</sub>
|
|
35
|
+
</p>
|
|
27
36
|
|
|
28
|
-
|
|
29
|
-
pnpm install --frozen-lockfile
|
|
30
|
-
pnpm run build:web
|
|
31
|
-
cargo run -p agentdock-server
|
|
32
|
-
```
|
|
37
|
+
## Install
|
|
33
38
|
|
|
34
|
-
|
|
39
|
+
Requires **Node.js 24+**, plus [Claude Code](https://www.npmjs.com/package/@anthropic-ai/claude-code) and/or [Codex](https://www.npmjs.com/package/@openai/codex) installed on the same machine.
|
|
35
40
|
|
|
36
|
-
|
|
41
|
+
```bash
|
|
42
|
+
npm install -g @wnzzer/agentdock # or try it once: npx @wnzzer/agentdock
|
|
43
|
+
```
|
|
37
44
|
|
|
38
|
-
|
|
45
|
+
One prebuilt binary per platform, with the web client and the native bridge inside it. npm downloads only the one matching your machine through `os`/`cpu` on optional dependencies; there is no postinstall step, so `--ignore-scripts` installs work.
|
|
39
46
|
|
|
40
|
-
|
|
47
|
+
| Platform | Prebuilt |
|
|
48
|
+
| -------- | --------------------------- |
|
|
49
|
+
| macOS | arm64 · x64 |
|
|
50
|
+
| Linux | x64 · arm64 (static musl) |
|
|
51
|
+
| Other | [build from source](#development) |
|
|
41
52
|
|
|
42
|
-
|
|
53
|
+
Not using npm? Every [release](https://github.com/wnzzer/agentdock/releases) attaches tarballs with a `SHA256SUMS`.
|
|
43
54
|
|
|
44
|
-
|
|
55
|
+
## Quick start
|
|
45
56
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
- Two-level workspace → session navigation, with one shared canvas across projects. Expanding/selecting a workspace does not replace existing panes. Files and Git actions stay bound to each pane's workspace; the explorer follows focus or can be pinned.
|
|
50
|
-
- **Load existing session** lists native Codex/Claude Code history belonging to the chosen workspace, supports fuzzy search, and links a selected history after confirmation. It resumes history, not an already-running external terminal.
|
|
51
|
-
- Structured Agent messages, folding tool cards, native approval/question cards, usage and turn status, with responsive controls for narrow layouts. Rust supervises a bounded Node JSONL bridge: Codex uses official `app-server`; Claude Code uses the user's existing CLI `stream-json` control interface. Neither adapter implements an Agent loop.
|
|
52
|
-
- Claude Code/Codex legacy PTY sessions and optional host-shell terminals remain available. A live PTY is never silently taken over by structured chat. Disconnect/reconnect preserves its running process.
|
|
53
|
-
- Confirmed, same-client endpoint/configuration switching while idle: close the old bridge, use a fresh native conversation and configuration generation, and retain earlier UI history without forwarding it or the old environment to the new endpoint.
|
|
54
|
-
- Process state and stream connection state are displayed separately. An 8-second WebSocket handshake watchdog reports an actionable connection failure instead of staying “connecting”; it does not automatically retry, restart a process, or replay user input.
|
|
55
|
-
- Custom profiles keep per-session endpoint snapshots, model and permission-intent mapping. Profile edits affect future sessions only.
|
|
56
|
-
- Advanced environment editors for profile defaults, new sessions, history loading and existing sessions. Host environment inheritance remains process-local; explicit overrides are validated and stored separately.
|
|
57
|
-
- **Import existing configuration** adds a reusable reference to the host's existing Codex/Claude Code home. New sessions can reuse its login, model, endpoint and native settings without copying credentials. This shared reference is explicitly different from an isolated custom profile.
|
|
58
|
-
- Profiles can fetch model IDs explicitly: native Codex uses app-server `model/list`; custom endpoints use the read-only models API. Manual model IDs/aliases are always available. Account access can differ from catalogue visibility.
|
|
59
|
-
- A new isolated/custom-profile session can override its model without changing its profile or other sessions. A host-reference session keeps its native model settings; an optional advanced process-environment overlay never writes back to the source configuration.
|
|
60
|
-
- Lazy expandable file tree with keyboard navigation and per-workspace remembered expansion, plus **Reveal in file tree** on previews.
|
|
61
|
-
- **Syntax highlighting and rendered Markdown** in the file pane. A `.md` file opens rendered, with its source one click away; code files are highlighted behind the editor, so editing and colour are not a choice between two modes. The highlighter and each grammar load on demand — a TypeScript file fetches about 11 kB and nothing else does — and a file past 512 kB stays plain rather than stuttering on every keystroke.
|
|
62
|
-
- **Workspace-wide file search**, in the tree and as `@path` completion in the composer. It uses the Codex app-server's own index, which honours `.gitignore` so build output and dependencies stay out, and which needs no account — verified against an empty `CODEX_HOME`. It therefore runs against a configuration directory holding no credentials, and is available to any session, not only Codex ones. Without Codex installed the tree falls back to filtering the entries it has already loaded, and says which of the two it is doing.
|
|
63
|
-
- Text edit/save with version conflicts, image/video/audio/PDF browser previews and download.
|
|
64
|
-
- First-class Git status/diff, staged/unstaged groups, file/all staging, unstaging and explicit commit.
|
|
65
|
-
- SQLite WAL metadata, schema 9, persisted layouts and sequenced conversation events. The recent transcript window is bounded; control anchors and pending approvals survive display-window trimming. UUID/SHA-256 submission receipts prevent replay across reconnects/restarts.
|
|
66
|
-
- Official-account records with private native config directories. Codex browser/device login, cancellation, token refresh, logout, available official quota information and eligible earned reset credits use the official client APIs. Claude login remains under the official client; usage is an explicit read of the official OAuth usage endpoint, while login/token refresh and quota reset remain unavailable. See [official account boundaries](docs/official-accounts.md).
|
|
67
|
-
- Local Host/Origin/CSRF checks; optional access-token login and HttpOnly cookie for private remote use.
|
|
57
|
+
```bash
|
|
58
|
+
agentdock # starts in the background and prints its URL
|
|
59
|
+
```
|
|
68
60
|
|
|
69
|
-
|
|
61
|
+
Open **http://127.0.0.1:28789/**, then:
|
|
70
62
|
|
|
71
|
-
|
|
63
|
+
1. **Pick a workspace** — any existing directory on the host.
|
|
64
|
+
2. **Reuse your sign-in** — *Endpoint profiles → Import existing configuration* references your existing `~/.claude` or `~/.codex`, so new sessions use the login, model and settings you already have. Nothing is copied.
|
|
65
|
+
3. **Create a session**, or **Load existing session** to resume a native Claude Code / Codex conversation that belongs to this workspace.
|
|
66
|
+
4. **Arrange the canvas** — drag sessions, files, Git and terminals into splits and tabs.
|
|
72
67
|
|
|
73
|
-
|
|
68
|
+
`agentdock` behaves as a gateway: it starts a detached server, waits until that server actually answers, and returns your shell. A failed start prints the reason from the log and exits non-zero instead of leaving a silent process.
|
|
74
69
|
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
70
|
+
```bash
|
|
71
|
+
agentdock status # URL, state and access token
|
|
72
|
+
agentdock logs
|
|
73
|
+
agentdock restart
|
|
74
|
+
agentdock stop
|
|
75
|
+
agentdock serve # foreground — what systemd or another supervisor should run
|
|
81
76
|
```
|
|
82
77
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
API-key profiles currently use a **reference**, e.g. `env:AGENTDOCK_SECRET_WORK`. Set that environment variable for the server; never enter the key into the profile form. AgentDock resolves the selected reference on the backend and injects its value into the selected child-process destination variable.
|
|
78
|
+
## Highlights
|
|
86
79
|
|
|
87
|
-
|
|
80
|
+
### 🧩 A canvas that docks anything
|
|
88
81
|
|
|
89
|
-
|
|
82
|
+
- Recursive horizontal/vertical splits, drag-to-edge docking, centre-drop tabs, resize with ratio snapping, `1:1` / `2×2` / `1:2:1` presets, maximize and restore.
|
|
83
|
+
- Panes squeezed below 280×180 fold into tabs without overwriting the saved layout, and come back when there is room.
|
|
84
|
+
- One shared canvas across every workspace: sessions from different projects sit side by side, while each file and Git pane stays bound to its own repository.
|
|
85
|
+
- Closing a pane never ends its process. Layouts persist server-side with compare-and-swap, so two browsers cannot silently overwrite each other.
|
|
90
86
|
|
|
91
|
-
|
|
87
|
+
### 🤖 Official agents, structured
|
|
92
88
|
|
|
93
|
-
|
|
89
|
+
- Messages, folding tool cards, native approval and question cards, usage, context ring and turn status — with **Interrupt** kept separate from a confirmed **End session**.
|
|
90
|
+
- Searchable model picker and reasoning effort, forwarded to each client's native flags. Claude Code's plan mode passes through as-is; where Codex has no equivalent, the option is refused rather than faked.
|
|
91
|
+
- Resume native history per workspace with fuzzy search. Legacy PTY sessions and optional host terminals remain available, and a live PTY is never silently taken over by structured chat.
|
|
92
|
+
- Disconnects keep processes alive. Process state and stream state are shown separately, and input is persisted before dispatch and never replayed after an uncertain outcome.
|
|
94
93
|
|
|
95
|
-
|
|
94
|
+
### 📁 Files and Git, first-class
|
|
96
95
|
|
|
97
|
-
-
|
|
98
|
-
-
|
|
99
|
-
-
|
|
100
|
-
- The original unset-versus-explicit `CODEX_HOME`/`CLAUDE_CONFIG_DIR` state is preserved. On macOS, explicitly setting even the default Claude directory can select a different Keychain login context. Explicit absolute paths keep their original spelling; relative directory variables are rejected because the workspace changes the child's working directory.
|
|
101
|
-
- AgentDock neither creates a new config home nor rewrites the source settings. The native client still manages its own credential refresh and conversation history. Existing login is reused when valid; reauthorization can still be required by the provider.
|
|
102
|
-
- Host-reference profiles support rename, advanced environment defaults and removal of the reference. Direct endpoint/model/proxy/permission fields and the native source identity remain read-only. Removing one never deletes the native home, logs out the account, or removes snapshots from existing sessions.
|
|
103
|
-
- Native clients inherit the backend process's environment, excluding AgentDock's private secret namespace/access token and required native-context removals. AgentDock does not source shell startup files or import aliases, shell functions, temporary exports or flags from another terminal. There is no generic import/conversion of CLIProxyAPI token JSON.
|
|
96
|
+
- Lazy file tree with keyboard navigation, workspace-wide search that honours `.gitignore`, and `@path` completion in the composer.
|
|
97
|
+
- Syntax highlighting behind the editor, rendered Markdown with source one click away, conflict-checked saves, and image / video / audio / PDF previews. Grammars load on demand.
|
|
98
|
+
- Git status and diff, staged/unstaged groups, per-file and all-file staging, unstaging and explicit commits — a top-level pane, not an editor afterthought.
|
|
104
99
|
|
|
105
|
-
|
|
100
|
+
### 🔐 Accounts, profiles and environment
|
|
106
101
|
|
|
107
|
-
|
|
102
|
+
- Reference the host's existing Claude Code / Codex configuration, or create isolated custom endpoint profiles with their own model and permission intent. Profile edits affect future sessions only.
|
|
103
|
+
- API keys are **references** such as `env:AGENTDOCK_SECRET_WORK`, resolved on the backend at launch — never typed into a form, never stored in SQLite.
|
|
104
|
+
- Per-session environment overlays with literal, secret-reference and explicit-unset entries; names that look like credentials are refused as literals.
|
|
105
|
+
- Official-account management through the official client APIs: Codex browser/device login, refresh, logout and quota; Claude usage read from the official endpoint. See [official account boundaries](docs/official-accounts.md).
|
|
108
106
|
|
|
109
|
-
|
|
107
|
+
### 🌐 Yours to reach
|
|
110
108
|
|
|
111
|
-
|
|
109
|
+
- Loopback by default. `agentdock --lan` binds every interface and issues an access token; Host / Origin / CSRF checks stay on either way.
|
|
110
|
+
- Chinese and English UI, with responsive layouts down to narrow screens.
|
|
111
|
+
- State lives in `~/.agentdock/` on your hardware: SQLite in WAL mode, `0700` configuration directories, and no telemetry.
|
|
112
112
|
|
|
113
|
-
|
|
113
|
+
## How it fits together
|
|
114
114
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
115
|
+
```text
|
|
116
|
+
Browser ── Vue 3 canvas: sessions · files · Git · terminals
|
|
117
|
+
│ HTTP + WebSocket, same origin
|
|
118
|
+
▼
|
|
119
|
+
agentdock-server (Rust) ─────────────── SQLite (WAL) · ~/.agentdock
|
|
120
|
+
├─ workspace / file / Git services paths canonicalised inside the workspace root
|
|
121
|
+
├─ PTY supervisor ──────────────────▶ host shell · legacy CLI sessions
|
|
122
|
+
└─ native bridge (Node, JSONL)
|
|
123
|
+
├─ codex app-server ──────────▶ official Codex
|
|
124
|
+
└─ claude stream-json ────────▶ official Claude Code
|
|
125
|
+
```
|
|
118
126
|
|
|
119
|
-
|
|
127
|
+
- The **server** owns protocol, auth, persistence and process supervision. It never executes an agent loop.
|
|
128
|
+
- The **native bridge** is a bounded Node subprocess that maps each client's official structured interface onto versioned session events. That is why Node is a requirement rather than an extra.
|
|
129
|
+
- The **layout engine** is the product core: agents, editors, Git and terminals are all just pane kinds, so new capabilities register as panes instead of reshaping the app.
|
|
120
130
|
|
|
121
|
-
|
|
131
|
+
More in [Architecture](docs/architecture.md) and [Structured agent UI](docs/structured-agent-ui.md).
|
|
122
132
|
|
|
123
|
-
|
|
124
|
-
- History loading with no overrides omits the environment field and preserves an already-imported session's map. Repeating an import with different explicit overrides returns a conflict (409); it never silently changes a running session.
|
|
125
|
-
- The inherited backend environment is not copied into SQLite or exposed by the editor. Another terminal's exports, shell startup configuration and an old session's temporary environment cannot be reconstructed from history. Native configuration files retain the CLI's own precedence; an environment overlay does not rewrite those files or promise to override every native setting.
|
|
126
|
-
- **Literal** assigns the exact value: `$PATH`, `${NAME}`, `~` and command-looking text are not shell-expanded. Literal values are plaintext local metadata, so never enter credentials there. **Secret reference** accepts only `env:AGENTDOCK_SECRET_NAME`; configure that variable for the backend and it is resolved only at launch, never returned as an editor value. **Unset** explicitly removes a child-process variable.
|
|
127
|
-
- Deleting an override is not the same as **Unset**. In a new-session draft it reveals any profile default; in an existing session's replacement map it drops that explicit value and leaves the base launch environment to apply. Native config-file settings still follow native-client behavior.
|
|
128
|
-
- Names use `[A-Za-z_][A-Za-z0-9_]{0,127}`. `HOME`, `USERPROFILE`, `PWD`, `OLDPWD`, `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `CLAUDECODE` and all `AGENTDOCK_*` names are reserved, case-insensitively. Names containing `TOKEN`, `SECRET`, `PASSWORD`, `PRIVATE_KEY`, `API_KEY` or `AUTHORIZATION`, and proxy/base URLs containing user information, require a secret reference instead of a literal value (or may be unset).
|
|
129
|
-
- Limits: 64 explicit entries and 64 KiB of serialized JSON; literal and resolved secret values are at most 8192 UTF-8 bytes and cannot contain NUL. Profile defaults and per-session overrides must also fit the limits after merging.
|
|
133
|
+
## Remote access
|
|
130
134
|
|
|
131
|
-
|
|
135
|
+
```bash
|
|
136
|
+
agentdock --lan # binds all interfaces, prints an access token
|
|
137
|
+
```
|
|
132
138
|
|
|
133
|
-
|
|
139
|
+
Traffic is plain HTTP, so on a network you do not control prefer SSH port forwarding —
|
|
134
140
|
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
AGENTDOCK_HOME # installation/state home; default ~/.agentdock for new installs
|
|
138
|
-
AGENTDOCK_STATE_DIR # optional persistent state directory
|
|
139
|
-
AGENTDOCK_ADDR # default 127.0.0.1:28789
|
|
140
|
-
AGENTDOCK_WEB_DIR # state-dir/web if installed, else source apps/web/dist
|
|
141
|
-
AGENTDOCK_NATIVE_BRIDGE # optional path to packages/native-bridge/history.mjs
|
|
142
|
-
AGENTDOCK_JS_RUNTIME # native helper/chat/account runtime; default node (absolute path supported)
|
|
143
|
-
AGENTDOCK_CHAT_BRIDGE # optional path to packages/native-bridge/chat.mjs
|
|
144
|
-
AGENTDOCK_ACCOUNT_BRIDGE # optional path to packages/native-bridge/account.mjs
|
|
145
|
-
AGENTDOCK_NODE_BIN # legacy runtime override, used only if JS_RUNTIME is unset/empty
|
|
146
|
-
AGENTDOCK_CODEX_HISTORY_DIR # optional history source; otherwise CODEX_HOME or ~/.codex
|
|
147
|
-
AGENTDOCK_CLAUDE_HISTORY_DIR # optional history source; otherwise CLAUDE_CONFIG_DIR or ~/.claude
|
|
148
|
-
AGENTDOCK_CLAUDE_BIN # optional absolute path to claude
|
|
149
|
-
AGENTDOCK_CODEX_BIN # optional absolute path to codex
|
|
150
|
-
AGENTDOCK_SHELL # optional shell; defaults to SHELL or /bin/sh
|
|
151
|
-
AGENTDOCK_BROWSE_ROOTS # optional directory-picker roots, OS path-list (macOS/Linux colon-separated)
|
|
152
|
-
AGENTDOCK_WORKSPACE_ROOTS # optional roots a new workspace may sit under; defaults to the browsing roots
|
|
153
|
-
AGENTDOCK_INSTANCE_LABEL # optional UI label for isolated preview deployments
|
|
141
|
+
```bash
|
|
142
|
+
ssh -L 28789:127.0.0.1:28789 user@server
|
|
154
143
|
```
|
|
155
144
|
|
|
156
|
-
|
|
145
|
+
— or put an HTTPS reverse proxy in front that preserves `Host` and WebSocket upgrades, and list its hostname in `AGENTDOCK_ALLOWED_ORIGINS`. Details in [Security and boundaries](docs/security.md#private-remote-access).
|
|
157
146
|
|
|
158
|
-
|
|
159
|
-
agentdock --lan
|
|
160
|
-
```
|
|
147
|
+
## Security
|
|
161
148
|
|
|
162
|
-
|
|
163
|
-
provide one, and prints it; `agentdock status` prints it again. The token is
|
|
164
|
-
kept in the state directory, readable only by its owner — a background gateway
|
|
165
|
-
cannot show it to you any other way, and deleting the file issues a new one.
|
|
149
|
+
AgentDock is a **single trusted user's host workspace, not a multi-tenant sandbox.**
|
|
166
150
|
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
Origin and `sec-fetch-site` checks either way.
|
|
151
|
+
- Anyone who can reach the API has the authority of the user running the server. Treat the access token as that user's credentials.
|
|
152
|
+
- File access is confined to workspace roots: paths are canonicalised, `.git`, `.agentdock` and client configuration files are refused, and deletion never follows a symlink out of the tree.
|
|
153
|
+
- **Agent processes are not confined by any of that.** `claude` and `codex` run with your full user permissions; what they can reach is decided by their own permission settings, not by this server.
|
|
154
|
+
- A non-loopback bind refuses to start without a token of 24+ characters, and Origin/Host must be allow-listed.
|
|
172
155
|
|
|
173
|
-
|
|
174
|
-
forwarding — `ssh -L 28789:127.0.0.1:28789 user@server` — or put an HTTPS
|
|
175
|
-
reverse proxy in front that preserves Host and WebSocket upgrades. Do not expose
|
|
176
|
-
this trusted-host workspace to untrusted users: whoever holds the token can run
|
|
177
|
-
agents, read and write files, and open terminals on that machine.
|
|
156
|
+
Read [Security and boundaries](docs/security.md) and [Permission boundary](docs/permission-boundary.md) before exposing it beyond localhost.
|
|
178
157
|
|
|
179
|
-
##
|
|
158
|
+
## Documentation
|
|
180
159
|
|
|
181
|
-
|
|
160
|
+
| Goal | Start here |
|
|
161
|
+
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
162
|
+
| Configure state, credentials and environment | [Configuration](docs/configuration.md) · [Endpoint profiles](docs/endpoint-profiles.md) |
|
|
163
|
+
| Sign in with official accounts | [Official accounts](docs/official-accounts.md) |
|
|
164
|
+
| Understand sessions, history and the canvas | [Sessions and the shared canvas](docs/sessions-and-canvas.md) · [Structured agent UI](docs/structured-agent-ui.md) |
|
|
165
|
+
| Expose it safely | [Security and boundaries](docs/security.md) · [Permission boundary](docs/permission-boundary.md) |
|
|
166
|
+
| Integrate or script against it | [API contract](docs/api.md) |
|
|
167
|
+
| See how it is built, and why | [Architecture](docs/architecture.md) · [Product boundary](docs/product-boundary.md) · [UI design](docs/ui-design.md) |
|
|
168
|
+
| Upgrade a running install | [Settings and update](docs/settings-update.md) |
|
|
169
|
+
| Check what has actually been verified | [Acceptance record](docs/mvp-status.md) |
|
|
182
170
|
|
|
183
|
-
|
|
171
|
+
## Development
|
|
184
172
|
|
|
185
|
-
|
|
186
|
-
- **Directory picker**: limited to `AGENTDOCK_BROWSE_ROOTS`, defaulting to the working directory and the server user's home.
|
|
187
|
-
- **New workspaces**: limited to `AGENTDOCK_WORKSPACE_ROOTS`, defaulting to the browsing roots. Workspaces created before this rule keep working; it governs new ones.
|
|
188
|
-
- **File read/write**: confined to a workspace root. Paths are canonicalised and anything resolving outside is refused, as are `.git`, `.agentdock` and client configuration files. Deleting never follows a symlink out of the tree.
|
|
189
|
-
- **Agent processes are not confined by any of the above.** `claude` and `codex` run with your full user permissions. AgentDock sets their working directory and forwards their permission prompts; it never answers one for you, and it never reads their credentials. What an Agent can reach is decided by that client's own permission settings, not by this server.
|
|
173
|
+
A Cargo workspace plus a pnpm workspace: Rust stable 1.89+, Node.js 24+ and pnpm 10.30.3.
|
|
190
174
|
|
|
191
|
-
|
|
175
|
+
```bash
|
|
176
|
+
git clone https://github.com/wnzzer/agentdock.git
|
|
177
|
+
cd agentdock
|
|
178
|
+
pnpm install --frozen-lockfile
|
|
179
|
+
pnpm run dev # Cargo + Vite → http://127.0.0.1:5173/
|
|
180
|
+
```
|
|
192
181
|
|
|
193
|
-
-
|
|
194
|
-
- State and database ownership locks prevent two new-version servers from managing the same sessions. Port binding and ownership checks happen before migration/reconciliation. `init` also respects these locks and never resets running-session status. Keep state on a local filesystem with working OS file locks; do not remove lock files while a process is alive.
|
|
195
|
-
- Terminal replay is the most recent 1 MiB in memory, not a durable transcript. After a server restart use the native client's history/resume workflow.
|
|
196
|
-
- Model-generation and paid API requests are not part of the automated tests; sign in or supply your own provider reference.
|
|
197
|
-
- No custom Agent reasoning loop, token-exchange server, provider reverse proxy, Keychain editor, automatic account import, strong cross-process credential isolation, hunk staging, Git network/PR workflow, LSP or computer-desktop control in this MVP.
|
|
198
|
-
- Media playback depends on browser codecs. Text editing limit: 2 MiB. Large Git output is rejected; no silent truncation.
|
|
199
|
-
- Common proxy support is HTTP/HTTPS without inline passwords. Claude Code does not support SOCKS. Empty proxy follows host settings; explicit profiles override inherited proxy variables for that process only.
|
|
200
|
-
- Model listing never performs inference. HTTP requests have time/body limits and do not follow redirects with credentials; non-compatible endpoints keep manual model entry as fallback.
|
|
201
|
-
- Resource guardrails bound layout depth/nodes, event windows and runtime replay. Managed process groups receive bounded cleanup; deliberately detached daemons remain outside that group boundary.
|
|
202
|
-
- macOS has been run locally. Linux has a CI target, not a claim of a completed deployment here.
|
|
182
|
+
Production-style run and the full gate:
|
|
203
183
|
|
|
204
|
-
|
|
184
|
+
```bash
|
|
185
|
+
pnpm run build:web && cargo run -p agentdock-server # → http://127.0.0.1:28789/
|
|
205
186
|
|
|
206
|
-
```sh
|
|
207
187
|
cargo fmt --all -- --check
|
|
208
188
|
cargo clippy --workspace --all-targets -- -D warnings
|
|
209
189
|
cargo test --workspace
|
|
210
190
|
pnpm run check
|
|
211
|
-
pnpm run build:web
|
|
212
191
|
```
|
|
213
192
|
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
193
|
+
| Path | What lives there |
|
|
194
|
+
| ------------------------ | ----------------------------------------------------------- |
|
|
195
|
+
| `crates/server` | HTTP/WebSocket API, daemon, security, accounts, workspace IO |
|
|
196
|
+
| `crates/agent-runtime` | Process and PTY supervision |
|
|
197
|
+
| `crates/persistence` | SQLite store and migrations (`migrations/`) |
|
|
198
|
+
| `crates/domain` | Shared domain model |
|
|
199
|
+
| `packages/native-bridge` | Node JSONL bridge to Claude Code and Codex |
|
|
200
|
+
| `packages/protocol` | DTOs and the layout model shared with the client |
|
|
201
|
+
| `apps/web` | Vue 3 + TypeScript client and the layout engine |
|
|
202
|
+
| `npm/` | Packaging for `@wnzzer/agentdock` and its platform packages |
|
|
217
203
|
|
|
218
|
-
|
|
204
|
+
See [Development](docs/development.md) for the dev loop, the read-only UI preview and deployment cautions.
|
|
219
205
|
|
|
220
|
-
|
|
206
|
+
## Status
|
|
221
207
|
|
|
222
|
-
|
|
208
|
+
AgentDock is an **MVP under active development**. It has been run locally on macOS; Linux is a CI build target, not yet a claim of a completed deployment. Implementation and fixture coverage do not mean every live provider or account flow has been exercised — what has actually been verified, and what has not, is written down in the [acceptance record](docs/mvp-status.md).
|
|
223
209
|
|
|
224
|
-
|
|
210
|
+
Deliberately out of scope for now: a custom agent loop, a provider reverse proxy, strong cross-process credential isolation, hunk-level staging, Git network/PR workflows, LSP and desktop control.
|
|
225
211
|
|
|
226
|
-
|
|
212
|
+
## License
|
|
227
213
|
|
|
228
|
-
|
|
214
|
+
[MIT](LICENSE). Bundled third-party material is listed in [third-party notices](docs/third-party-notices.md).
|
|
229
215
|
|
|
230
|
-
|
|
216
|
+
Claude Code and Codex are products of Anthropic and OpenAI respectively. AgentDock is an independent project that launches the official clients you install yourself; it is not affiliated with or endorsed by either company.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wnzzer/agentdock",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.13",
|
|
4
4
|
"description": "Remote multi-agent development workspace for the official Claude Code and Codex CLIs",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"homepage": "https://github.com/wnzzer/agentdock",
|
|
@@ -22,10 +22,10 @@
|
|
|
22
22
|
"agentdock": "bin/agentdock.js"
|
|
23
23
|
},
|
|
24
24
|
"optionalDependencies": {
|
|
25
|
-
"@wnzzer/agentdock-darwin-arm64": "0.1.
|
|
26
|
-
"@wnzzer/agentdock-darwin-x64": "0.1.
|
|
27
|
-
"@wnzzer/agentdock-linux-x64": "0.1.
|
|
28
|
-
"@wnzzer/agentdock-linux-arm64": "0.1.
|
|
25
|
+
"@wnzzer/agentdock-darwin-arm64": "0.1.13",
|
|
26
|
+
"@wnzzer/agentdock-darwin-x64": "0.1.13",
|
|
27
|
+
"@wnzzer/agentdock-linux-x64": "0.1.13",
|
|
28
|
+
"@wnzzer/agentdock-linux-arm64": "0.1.13"
|
|
29
29
|
},
|
|
30
30
|
"files": [
|
|
31
31
|
"bin/",
|