totopo 1.0.4 → 1.0.5

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.
Files changed (2) hide show
  1. package/README.md +18 -34
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -2,36 +2,33 @@
2
2
 
3
3
  <img src=".github/assets/logo.png" alt="totopo" width="100%" />
4
4
 
5
- A simple CLI to spin up a sandboxed Docker environment for AI coding agents.
5
+ A simple CLI to spin up a sandboxed Docker environment for AI coding agents — pre-installed tools, any git project.
6
6
 
7
7
  ![npm version](https://img.shields.io/npm/v/totopo)
8
8
  ![npm downloads](https://img.shields.io/npm/dm/totopo)
9
9
  ![license](https://img.shields.io/npm/l/totopo)
10
10
 
11
- ## What is totopo?
11
+ ## Why totopo?
12
12
 
13
- `npx totopo` spins up a secure, isolated dev container for any git project — with AI coding tools pre-installed — in a single command.
13
+ Here's the thing about AI agents: they're probabilistic. They occasionally misinterpret instructions, take unexpected shortcuts, or simply get it wrong. Most of the time they're fine. But "most of the time" isn't a great argument for giving them unrestricted access to your machine, your credentials, and your remote repositories.
14
14
 
15
- There are other solutions that offer more hardened security setups, and others with a richer feature set. totopo is neither of those. It is my own take on what makes a good balance between excellent developer experience and a sensible basic sandboxing setup.
15
+ totopo draws a simple boundary: agents get a full, capable environment to work in — they just can't touch anything outside the project, and they can't reach your remote. That's it. No domain whitelisting, no paranoia, no compromise on what the agent can actually do.
16
+ Reasonable containment for non-deterministic tools. Nothing more, nothing less.
16
17
 
17
- ---
18
+ Note: no sandbox substitutes for good judgment. Consider keeping any sensitive secrets or privileged scripts away from your agents.
18
19
 
19
20
  ## Features at a Glance
20
21
 
21
22
  - **Sandboxed Docker container** — your code runs in an isolated environment with strict filesystem and privilege boundaries
22
23
  - **Agents can't reach remote** — push, pull, fetch, and clone are blocked inside the container, preventing agents from accidentally affecting your remote repositories
23
- - **Scoped mounts** — expose only the files and directories the agent needs, nothing more
24
- - **AI coding CLIs with persistent sessions** — Claude Code, OpenCode, and Codex pre-installed, with conversation history that survives restarts and rebuilds
24
+ - **AI CLIs with persistent sessions** — OpenCode, Claude Code and Codex pre-installed, with conversation history that survives restarts and rebuilds
25
25
  - **Host-mirror or generic runtime** — use a standard dev container, or let totopo match the container environment to your host so the agent works in the exact same setup as your codebase
26
-
27
- ---
26
+ - **Scoped mounts** — expose only the files and directories the agent needs, nothing more
28
27
 
29
28
  ## Requirements
30
29
 
31
- - [Docker](https://www.docker.com/products/docker-desktop/)
32
- - [git](https://git-scm.com/)
33
-
34
- ---
30
+ - [Docker](https://www.docker.com/products/docker-desktop/) - used to build and run the sandboxed environment
31
+ - [git](https://git-scm.com/) - safeguard to ensure agents only run in projects with version control in place
35
32
 
36
33
  ## Quick Start
37
34
 
@@ -42,15 +39,11 @@ npx totopo
42
39
 
43
40
  Select **Open session** from the menu. If `.totopo/` doesn't exist yet, a one-time onboarding flow runs first. The first run builds the Docker image. Subsequent starts are fast.
44
41
 
45
- <!-- VIDEO: First-time setup — running `npx totopo` in a fresh repo, selecting a runtime mode, and waiting for the Docker image to build for the first time.
46
42
  ![First-time setup](.github/assets/demo-onboarding.gif)
47
- -->
43
+ *First-time setup — running `npx totopo` in a fresh repo, selecting a runtime mode, and waiting for the Docker image to build for the first time.*
48
44
 
49
- <!-- VIDEO: Starting a session once the container is already built — opening a session, running an AI tool, exiting.
50
45
  ![Quick start](.github/assets/demo-quickstart.gif)
51
- -->
52
-
53
- ---
46
+ *Starting a session once the container is already built — opening a session, running an AI tool, exiting.*
54
47
 
55
48
  ## Features
56
49
 
@@ -77,11 +70,10 @@ In both scoped modes, `.git` is intentionally not mounted. Mounting `.git` would
77
70
 
78
71
  Scoped sessions are well-suited for focused tasks where you want to give the agent a narrow, explicit view of your codebase.
79
72
 
80
- <!-- VIDEO: Using scoped mounts — selecting cwd and selective modes, showing what the agent can and can't see inside the container.
81
73
  ![Scoped sandboxing](.github/assets/demo-scoped.gif)
82
- -->
74
+ *Using scoped mounts — selecting cwd and selective modes, showing what the agent can and can't see inside the container.*
83
75
 
84
- ### AI tools pre-installed
76
+ ### AI CLIs with persistent sessions
85
77
 
86
78
  The container comes with the major AI coding CLIs ready to use out of the box:
87
79
 
@@ -91,6 +83,8 @@ claude # Claude Code (Anthropic)
91
83
  codex # Codex (OpenAI)
92
84
  ```
93
85
 
86
+ Agent session data is scoped per project — each repository gets its own isolated history, so agents don't bleed context between projects. To clear memory, run `npx totopo` and navigate to Advanced > Clear agent memory. This stops the container if running and removes the .totopo/agents/ directory.
87
+
94
88
  ### Dev container runtime
95
89
 
96
90
  Choose between two modes:
@@ -100,12 +94,6 @@ Choose between two modes:
100
94
 
101
95
  Either way, basic dev tools and all three AI CLIs are always included.
102
96
 
103
- <!-- VIDEO: Switching runtime modes in the settings menu, selecting tools, and triggering a container rebuild.
104
- ![Runtime switching](.github/assets/demo-runtime.gif)
105
- -->
106
-
107
- ---
108
-
109
97
  ## What gets created in your project
110
98
 
111
99
  ```
@@ -123,16 +111,12 @@ your-project/
123
111
  ~/.totopo/.env # API keys — global, outside all repos, never mounted into container
124
112
  ```
125
113
 
126
- Agent session history and conversation data are persisted in `agents/` across container rebuilds and restarts. This directory is gitignored — session data stays local to your machine.
127
-
128
- ---
114
+ Agent session history and conversation data are persisted in the `agents` directory across container rebuilds and restarts. This directory is gitignored so session data stays local to your machine.
129
115
 
130
116
  ## Limitations
131
117
 
132
118
  **Audio / microphone** — the image includes `sox` (required by Claude Code for voice mode), but audio passthrough from the host depends on your OS. macOS, Linux, and Windows each require different device configuration. If you need voice mode, set up audio passthrough manually for your platform.
133
119
 
134
- ---
135
-
136
120
  ## Disclaimer
137
121
 
138
- totopo is MIT licensed and fully open source — fork it, adapt it, build on it. Issues are welcome but response times aren't guaranteed. Use at your own risk.
122
+ MIT licensed and fully open source. Fork it, adapt it, make it yours. Issues are welcome — no promises on response time. Use at your own risk.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "totopo",
3
- "version": "1.0.4",
3
+ "version": "1.0.5",
4
4
  "description": "Secure AI Box — isolated dev environments for AI coding assistants",
5
5
  "type": "module",
6
6
  "bin": {