The way sbx kits work is confusing

[toby-griffiths]

I very much welcome the idea of kits for configuring sandboxes, however I'm finding myself rather frustrated attempting to get things working as I think they should, so thought it might be helpful to feed back to help improve user experience.

1. Kit network policies don't seem to work. I've allowed access to github.com:443 both in a kits/network kit, and in a kits/plugins kit to alow me to install plugins via kits during creation, however I get the error that no policy allows access to github.com; (see also clarification on network policy with kit #140);
2. If running claude plugins install … during creation install reports that the marketplace is not available;
3. Trying to use startup:, rather than install: to install the plugins during creation it reports "Registering 20 startup command(s) (will run on every container start)...", however then running the sandbox does NOT install any of the plugins requested (& no error output), but just jumps straight into the Claude session, with no plugins installed;
4. It seems that kits are now consolidated before being run, rather than being run in the order defined, so it's not possible to allow network access, install some plugins, then revoke the network access; I believe this has changed since previous versions?;
5. Installing Claude pluigns during creation, using install seems to install the plugins (after globally allowing github.com:443 access, as above), but then when I run the sandbox the plugins are not showing as installed;
6. Finally got plugin installed & working by creating the sandbox first (without kits), then running the kits on the created sandbox (sbx kit add …), and then finally running the sandbox;

Hoping this feedback helps make things a little simpler. Happy to break this down into separate tickets if it helps?

[dimon222]

I double on this. Its unclear how to use kits properly. Documentation doesn't cover it enough.

[kiview]

Hey folks, thanks for the feedback. We are publishing an updated spec of kits soon (it is already supported in the current 0.34 release), and plan to focus on working with the community to make it easier to adopt, but also incorporate feedback.

We take this feedback serious @toby-griffiths and @dimon222, but since this issue as-is is not that easily actionable, I'll close this. Maybe we can move it over to a GitHub discussion instead (will ask the team if we should adopt it 🙂 ).

[kaihendry]

I find it really hard and so does Claude to figure out how to copy files into place! End up doing crazy things like: https://github.com/kaihendry/claude-code-settings-tests/blob/main/kit/spec.yaml

[H0R5E]

A big one on my wishlist for kits would be the ability to pass through environmental variables from the host with interpolation in a similar way to compose files. E.g.:

environment:
  variables:
    MY_TOOL_WORKSPACE: ${MY_TOOL_WORKSPACE}

This is desirable to me for a number of reasons including avoiding accidental commit of sensitive values and project specific configuration.

[kaihendry]

I think you can do that with sbx secrets iirc

[H0R5E]

Only for variables that get substituted in the proxy. AWS requests are signed using the keys before sending, so it doesn't work in that case, for instance. Something like #223 would help with this kind of issue, but beyond the secrets I believe there is value in being able to configure a kit file with host variables.

[H0R5E]

Also, the secrets API is kinda janky for me. I can't get a sandbox scoped github token to work for love nor money (when combined with a kit, I should add).

[jstephenson]

I would echo the OP's pain re trying to install a Claude plugin via setup commands. The operations (and their order) when an off-the-shelf sandbox (like the built-in Claude Code one) is started is inscrutable and, so far as I can tell, not documented. I think this kit from sbx-kits-contrib does a good job of illustrating pain of this type: https://github.com/docker/sbx-kits-contrib/blob/main/claude-mem/spec.yaml

[ghdoergeloh]

I like docker compose.yaml and devcontainer.json as configuration for container. It would be nice to have some sort of that. I hate to setup everything with cli commands. Especially if you want to share the settings in your team.

• Defining environment variables (instead of writing something into /etc/sandbox-persistent.sh)
• Mounting volumes/directories where they belong (claude state with session history)
• Publishing Ports
• I also like to use unique secrets per sandbox: I have Project A and Project B. The sandboxes should not mix things up so I give each a scoped fine grained access token
• in docker I used to define the env in a file or I used secrets in docker swarm and referenced them in the compose file. Or look at k8s manifests. You could define secrets in one file and reference them in your main manifest.
• I even still need to give the sandbox a name even though the kit defines a name...

There are so many paragons on how to define your sandbox/container as code. The more you lean on them, the easier it will be for developers to adapt sbx.

Guys, you are docker. Do not reinvent the wheel 😜. I am sure you will find a solution to run sandboxes as easy as these including the proxy, which is a wonderful additional feature to keep secrets separated from the ai which other container solutions do not have. 🚀

[rltas]

@ghdoergeloh are you aware there's https://docs.docker.com/ai/sandboxes/configuration/environment-files/ now?

[ghdoergeloh]

There it is 🎉

Sorry. I did not see it yet. That looks great!

Works almost perfect for me.

I just do not see a solution for custom secrets:
sbx secret set-custom --host gitlab.com --host api.gitlab.com --env GITLAB_TOKEN
Can you tell me how to do that?

Next step would be to use sbx as a runtime for devcontainer (if that is possible). Using kata on linux you could (in theory - did not test it) run qemu or firecracker vms as OCI compatible devcontainer. The same concept for sbx including secrets and proxy config would be perfect for me.

[ghdoergeloh]

I think I'm getting there:

So you define templates (docker images - correct?), you add an agent via kit kind: sandbox, you add tools with kit kind: mixin and finally define the sandbox environment for your project by using the sandbox and mixin definition in a .sbxenv.yaml:

So to use gitlab I would install and define it through a kit kind: mixin:

schemaVersion: "2"
kind: mixin
name: gitlab

permissions:
  network:
    allow:
      - gitlab.com

credentials:
  - service: gitlab
    description: GitLab API token for glab and git over HTTPS
    apiKey:
      name: GITLAB_TOKEN
      proxyManaged: true
      inject:
        - domain: gitlab.com
          header: Authorization
          format: "Bearer %s"

setup:
  install:
    - command: "apt-get update && apt-get install -y glab"
      user: "0"
    - command: "git config --global credential.helper '!glab auth git-credential'"
      user: "1000"

BTW: The credential inject with scheme: bearer is not working in v0.39.0 (A Bug?). You need to define it the header/format.

And then I define my .sbxenv.yaml:

schemaVersion: "1"
name: my-project
agent: claude
workspace: ./workspace

kits:
  - ./kit/gitlab

secrets:
  gitlab:
    ref: op://Employee/Gitlab Access Token - my-project/credential

bindings:
  gitlab:
    apiKey:
      domains:
        - gitlab.com

# optionally to store claude state (sessions, memory and so on) on my local disc:

additionalWorkspaces:
  - path: ./claude-state
 
env:
  CLAUDE_CONFIG_DIR: $PWD/claude-state