feat(cloudcli): add secure CloudCLI workspace module

[Edd88-pixel]

Description

Adds a community CloudCLI module that installs the pinned npm package in an isolated per-module runtime and exposes the service through an owner-only Coder app.

The module binds CloudCLI explicitly to 127.0.0.1:3001, uses the /health endpoint for readiness, preserves existing coding-agent installations and authentication, and supports an optional validated workspaces_root to limit project discovery. Startup is idempotent and refuses occupied or non-loopback listeners without terminating unrelated processes. The start pipeline allows a slow first-time npm installation to complete before launching CloudCLI.

The registry catalog uses the bundled CloudCLI icon. Coder deployments that do not provide /icon/cloudcli.svg may not render the in-workspace app and script icon; this does not affect module operation.

Type of Change

• New module
• New template
• Bug fix
• Feature/enhancement
• Documentation
• Other

Module Information

Path: registry/edd88-pixel/modules/cloudcli
New version: v1.0.0
Breaking change: [ ] Yes [x] No

Testing & Validation

• Tests pass (bun test)
• Code formatted (bun fmt)
• Changes tested locally

Executed successfully:

• bun install
• bun run fmt
• bun run shellcheck
• bun run tftest with explicit changed-module inputs
• bun run tstest with explicit changed-module inputs: 10 passed, 127 assertions
• terraform init -upgrade
• terraform validate
• terraform test -verbose: 9 passed
• bun test main.test.ts: 10 passed, 127 assertions
• ./scripts/terraform_validate.sh with explicit ALL_CHANGED_FILES and MODULE_CHANGED_FILES
• go build ./cmd/readmevalidation && ./readmevalidation
• Fresh Coder v2.33.11 workspace E2E using the Docker template provider and a non-root agent: an eight-minute first installation completed, the agent reached ready, and the Coder app reached healthy
• Runtime verification in the provisioned workspace: @cloudcli-ai/cloudcli@1.35.0, successful /health, live PID, listener 127.0.0.1:3001, and no wildcard listener
• Coder app-proxy browser E2E: created the single-user CloudCLI account, completed setup, and reached the CloudCLI v1.35.0 project dashboard

Related Issues

Closes #868

[bpmct]

Fresh Coder v2.33.11 workspace E2E using the Docker template provider and a non-root agent: an eight-minute first installation completed, the agent reached ready, and the Coder app reached healthy

This is kind of a slow first installation. I'm wondering if we should optionally allow people to use an image with it pre-baked.

[Edd88-pixel]

@bpmct Good point. The eight-minute result was a cold install; subsequent starts reuse the installed version. I can add an optional install_cloudcli input to support pre-baked images

[bpmct]

Awesome. Do you know of any pre-baked images that exist? If not, perhaps we could provide one (I could add something to the coder/images repo)

[Edd88-pixel]

CloudCLI publishes Docker Sandbox images (https://hub.docker.com/r/cloudcliai/sandbox), but they are not designed specifically for Coder workspaces. A dedicated image in coder/images would likely be a better fit. nice idea

[bpmct]

CloudCLI publishes Docker Sandbox images (https://hub.docker.com/r/cloudcliai/sandbox), but they are not designed specifically for Coder workspaces. A dedicated image in coder/images would likely be a better fit. nice idea

Oh awesome find! Honestly, given they do have Docker Sandbox images my preference would be to use/recommend their official "sandbox" images (even if it means documenting an example template in the README because those will be more likely to be maintained. There aren't many requirements for an image to work with Coder, so it's at least worth testing

If it doesn't work, I'm happy to fall back to making one in coder/images, but my preference is always to fall back onto "official" images when possible

[Edd88-pixel]

This makes sense. I completely agree with you and I just tried it and it works quite well 🙂

[bpmct]

Awesome, thanks for looking into that 🙂

[bpmct]

Just tried it out! Some feedback

1. Would love to avoid the "account setup" process since it's under a protected user-only URL in single-user mode. Is there a way to disable this entirely? Based on initial research, it seems like "no" but that would be a good feature request for them.
2. We should probably document in the example snippet in the README that you need an agent CLI installed in the workspace, and maybe even a snippet with our Claude Code (or any) module so that copying it over will work by default without erroring about a missing CLI
3. Regarding the icon, can you either submit a PR to coder/coder to add it, or simply link to https://avatars.githubusercontent.com/u/252026187?s=200&v=4? Either is fine 🤷🏼
4. Seeing this in the logs is a bit jarring given everything ended up coming online, can we suppress the curl warnings and put something more chill like "Waiting for CloudCLI to come online..."

[bpmct]

Adding @DevelopmentCats as a reviewer too as I'm sure he'll have some stylistic reviews too

[DevelopmentCats]

Honestly style wise everything looks great here. It looks like everything passed our CI checks as well.

I will give this a test as well but it looks like Ben picked out most of the key points I noticed, I will also follow up with some review comments as well since there are a few things worth addressing/changing

[Edd88-pixel]

thank you for your feedback and I am working hard to resolve your various comments and proposals

[Edd88-pixel]

@bpmct Thanks — I addressed points 2–4 in 6e981e9: the README now includes the agent prerequisite and a Claude Code example, the module uses the external CloudCLI icon, and startup polling no longer emits transient curl warnings. CloudCLI OSS 1.35.0 does not provide a supported option to skip the initial account setup, so I documented it as a one-time step rather than bypassing its authentication.

[Edd88-pixel]

@DevelopmentCats I tested path-based mode in a full Coder workspace. CloudCLI 1.35.0 uses root-relative /assets, /api, /ws, and /shell routes, so with subdomain = false the HTML loads but the UI remains blank. Exposing this option would currently create a broken configuration. I kept subdomain mode mandatory and documented

[Edd88-pixel]

@bpmct can you review ?

[DevelopmentCats]

@DevelopmentCats I tested path-based mode in a full Coder workspace. CloudCLI 1.35.0 uses root-relative /assets, /api, /ws, and /shell routes, so with subdomain = false the HTML loads but the UI remains blank. Exposing this option would currently create a broken configuration. I kept subdomain mode mandatory and documented

Ahh yeah I see that they don't have a configurable base domain path in the product. I will give this another review.

This would also make a good feature request for cloud-cli as well.