bug(gateway): 0.0.96 rejects sandbox names >19 chars, breaking the OpenClaw integration #2651
Description
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(releasev0.0.96) - Docker compute driver, Linux x86_64
- OpenClaw agent runtime via the
openshellplugin
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.
Activity
krishicks commentedon Aug 7, 2026
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:
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 = 61Twenty 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:
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?
sallyom commentedon Aug 18, 2026
This was recently fixed in OpenClaw with PR #115058 (openclaw/openclaw#115058).
It changed OpenShell sandbox names to exactly 19 characters: oc- plus a 16-character hash.
The next OpenClaw stable release will include the fix. Currently, fix is in Beta:
2026.8.1-beta.2