bug(gateway): 0.0.96 rejects sandbox names >19 chars, breaking the OpenClaw integration

[rocket-turkey]

Summary

OpenShell 0.0.96 enforces a hard 19-character maximum on sandbox names. The gateway rejects any longer name with gRPC INVALID_ARGUMENT. This makes 0.0.96 unusable with the official OpenClaw integration, whose sandbox names are structurally ≥24 characters and cannot be shortened through configuration.

Environment

• OpenShell gateway 0.0.96 (release v0.0.96)
• Docker compute driver, Linux x86_64
• OpenClaw agent runtime via the openshell plugin

Reproduction

CreateSandbox (or openshell sandbox create --name <name>) with a name longer than 19 characters is rejected:

$ openshell sandbox create --name openclaw-agent-dev-abcf4511 --from openclaw -- echo hi
Error:   × code: 'Client specified an invalid argument',
  message: "name exceeds maximum length (27 > 19)"

A name of exactly 19 characters works:

$ openshell sandbox create --name openclaw-agent-dev1 --from openclaw -- echo hi
Created sandbox: openclaw-agent-dev1

Why this breaks the OpenClaw integration

The OpenClaw integration names each agent's sandbox openclaw-agent-<agentId>-<8-hex-hash>. The fixed prefix openclaw-agent- is 15 characters, plus a hyphen and an 8-character hash — so every generated name is ≥24 characters before the agent id, and can never fit within 19.

There is no configuration lever to reconcile this: no sandbox-name/prefix/length key in the openshell plugin config, none in the per-agent sandbox config, and no gateway-side limit override. The gateway therefore rejects CreateSandbox for every OpenClaw agent, and no sandbox can be created at all.

Regression

The same integration and the same ≥24-character names worked on 0.0.85; the 19-character limit appears to be introduced in a later 0.0.9x release. Downgrading is not a clean workaround because 0.0.96 migrates the gateway state DB forward, and an older gateway then refuses to start against the migrated schema (migration N was previously applied but is missing in the resolved migrations).

Ask

One of:

• Raise or remove the 19-character sandbox-name limit, or make it configurable; and/or
• Document the limit and coordinate with the OpenClaw integration so its generated names fit (shorter prefix, shorter hash, or a configurable name).

If 19 is a hard downstream constraint (a Docker/Kubernetes/DNS-label budget), it would help to state that in the error and in the docs, so integrations can generate names accordingly.

[krishicks]

Triage by gpt-5.6-sol medium:

The core claim in issue #2651 is correct: OpenShell enforces a gateway-wide 19-byte/character maximum on sandbox names.

The limit is defined here:

• crates/openshell-server/src/grpc/mod.rs:125
• crates/openshell-server/src/grpc/validation.rs:167
• crates/openshell-server/src/grpc/sandbox.rs:215

The resulting error is exactly:

name exceeds maximum length (<length> > 19)

Why 19?

It is a service-routing hostname budget, not a Docker constraint:

{workspace}--{sandbox}--{service}.{base-domain}

The first hostname label must be at most 63 characters. The implementation assigns every component an equal worst-case budget:

19 + 2 + 19 + 2 + 19 = 61

Twenty characters each would produce 64. The rationale is documented immediately above the constant and implemented in crates/
openshell-server/src/service_routing.rs:77. The -- separators also make the three components unambiguous to the hostname parser.

git history identifies the introduction as:

5952a5a feat(workspace): add workspace resource model with scoping, membershi… (#2243)

That commit:

• Added workspace-prefixed service hostnames.
• Added MAX_ROUTABLE_NAME_LEN.
• Changed sandbox validation from MAX_NAME_LEN—253 characters—to 19.
• Explicitly shortened tests and examples “to comply with MAX_ROUTABLE_NAME_LEN.”
• Landed after v0.0.87 and before v0.0.88, so the regression begins in v0.0.88, earlier than the issue suggests.

The RFC confirms the architectural motivation: workspace scoping changed service URLs from two components to a consistently parseable two-or-three-component form. See rfc/0011-multi-player-design/README.md:1134.

One important nuance: this is a conservative global restriction. Kubernetes only constructs {workspace}--{sandbox} and independently validates the combined name against 63 characters in crates/openshell-driver-kubernetes/src/driver.rs:1178. Docker and Podman do not require a 19-character limit. OpenShell imposes it at sandbox creation so every sandbox can later expose a maximally named service, even when service routing is unused or disabled.

So the likely conclusion is: the limit was deliberately introduced for deterministic service-routing hostnames, but applying a fixed equal-share budget to all sandbox names is unnecessarily restrictive for many cases. The issue also correctly exposes a documentation gap: workspace CLI help mentions 19 characters, while sandbox creation help and published sandbox documentation do not.

@derekwaynecarr Given you authored 5952a5a, can you take a look at this?