You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Use a bring-your-own-cloud (BYOC) environment when an administrator has already provisioned a self-hosted Qoder environment and, optionally, a tunnel to private services. OpenCMA references those resources; it does not own their lifecycle.
4
+
5
+
## Prerequisites
6
+
7
+
Ask the environment administrator for:
8
+
9
+
- an environment ID, such as `env_00xxxx`;
10
+
- a tunnel ID, such as `tnl_00xxxx`, when the agent needs access to private services;
11
+
- the Qoder credentials needed to manage the agent and start sessions.
12
+
13
+
Do not commit real IDs, private hostnames, or credentials. Use environment variables for credentials and keep live deployment configurations outside the repository.
14
+
15
+
## Configure the external resources
16
+
17
+
Declare the provisioned environment with `environment_id` and `self_hosted`. Declare a tunnel by its existing ID, then reference both from the agent.
18
+
19
+
```yaml
20
+
version: "1"
21
+
22
+
providers:
23
+
qoder:
24
+
api_key: ${QODER_PAT}
25
+
26
+
defaults:
27
+
provider: qoder
28
+
29
+
environments:
30
+
byoc-environment:
31
+
environment_id: env_00xxxx
32
+
config:
33
+
type: self_hosted
34
+
35
+
tunnels:
36
+
internal-network:
37
+
tunnel_id: tnl_00xxxx
38
+
39
+
agents:
40
+
private-service-assistant:
41
+
model: qmodel_latest
42
+
instructions: You can use the configured private services.
43
+
environment: byoc-environment
44
+
tunnel: internal-network
45
+
tools:
46
+
builtin: [Bash, Read]
47
+
```
48
+
49
+
`tunnel` is supported only for Qoder BYOC sessions and deployments. Omit the entire `tunnels` section and the agent's `tunnel` field when no private-network tunnel is needed.
50
+
51
+
## Apply and run
52
+
53
+
Apply the configuration to provision or update managed resources such as the agent. The declared environment and tunnel are only recorded as references.
54
+
55
+
```bash
56
+
agents apply -f agents.yaml
57
+
agents session run "Check the private service status" --agent private-service-assistant -f agents.yaml
58
+
```
59
+
60
+
You can override the configured IDs for a one-off session without changing the YAML:
61
+
62
+
```bash
63
+
agents session run "Check the private service status" \
64
+
--agent private-service-assistant \
65
+
--environment-id env_00xxxx \
66
+
--tunnel-id tnl_00xxxx \
67
+
-f agents.yaml
68
+
```
69
+
70
+
## Lifecycle and cleanup
71
+
72
+
When `environment_id` is present, OpenCMA never creates, updates, or remotely deletes that environment. Tunnels are always references and are never managed by OpenCMA.
73
+
74
+
OpenCMA records external ownership in its local state, and the record is sticky:
75
+
76
+
- Remove the environment declaration entirely and run `agents apply` or `agents destroy`: only the local state record is removed; the administrator-managed environment remains intact.
77
+
- Remove only the `environment_id` line while keeping the environment block: `plan`/`apply` fail with an `plan.environment.ownership_transition` error. Silently converting the reference into a managed resource would let OpenCMA modify — and eventually delete — a remote environment it does not own. To take over management deliberately, release the reference first with `agents state rm environment.<name>` and adopt the remote with `agents state import`.
78
+
- Point `environment_id` at a different existing environment: the reference is re-recorded and any deployments using it are updated. If the environment was previously managed by OpenCMA under a different remote ID, `plan` warns that the old remote is no longer tracked.
79
+
80
+
Deleting an agent, session, vault, or other managed resource still follows its normal lifecycle. Use the provider's administrator tooling to modify or delete BYOC environments and tunnels.
81
+
82
+
## Deployments and tunnels
83
+
84
+
A deployment that references the BYOC environment runs in that environment, and changing the referenced `environment_id` value updates the deployment on the next `apply`. Qoder's deployment API currently rejects `tunnel_id`, however, so a declared (or agent-inherited) tunnel is not sent with the deployment: scheduled and triggered runs execute without the tunnel, and `validate`/`plan` emits a `qoder.deployment.tunnel.unsupported` warning. Use sessions for workloads that need private-network MCP access.
85
+
86
+
## Troubleshooting
87
+
88
+
| Symptom | Check |
89
+
|--------|-------|
90
+
| Session cannot reach a private service | Confirm the supplied tunnel ID is enabled for the environment and that the service hostname is reachable from the private network. |
91
+
| `Tunnel '...' is not defined in config` | Add the name under `tunnels`, or pass `--tunnel-id` for a one-off session. |
92
+
| Tunnel unsupported diagnostic | Ensure the agent or deployment targets Qoder; tunnels are not sent to other providers. |
93
+
| Environment cannot be resolved | Verify the administrator-provided `environment_id` and the agent's `environment` reference. |
94
+
| `plan.environment.ownership_transition` error | Restore `environment_id`, or release the reference with `agents state rm environment.<name>` before managing the environment with OpenCMA. |
95
+
| `qoder.deployment.tunnel.unsupported` warning | Expected: Qoder deployments cannot carry a tunnel today. Use sessions for private-network MCP access. |
96
+
97
+
For field definitions, see the [configuration reference](../reference/configuration.md).
| `environment_id` | string | no | Existing environment ID. When present, OpenCMA never creates, updates, or deletes the remote environment. Removing this line later is blocked as an ownership error — release first with `agents state rm` (see [Use BYOC environments](../guides/use-byoc-environments.md)). |
88
+
| `config.type` | `"cloud"` \| `"self_hosted"` | yes | Environment type. `self_hosted` is used for Qoder BYOC. |
| `metadata` | map<string,string> | no | Free-form metadata. |
91
95
96
+
## Tunnel (Qoder BYOC)
97
+
98
+
```yaml
99
+
tunnels:
100
+
internal-network:
101
+
tunnel_id: tnl_00xxxx
102
+
```
103
+
104
+
Tunnels are existing Qoder resources allocated by the BYOC administrator. They are passed only when a Qoder session/deployment is created and are never created, updated, or deleted by OpenCMA. See [Use BYOC environments](../guides/use-byoc-environments.md) for a complete setup and lifecycle guide.
105
+
92
106
## Vault
93
107
94
108
```yaml
@@ -166,6 +180,7 @@ agents:
166
180
model: <string> | { <provider>: <string> }
167
181
instructions: <string> | <path>
168
182
environment: <string>
183
+
tunnel: <string> # optional; Qoder BYOC tunnel name
tunnel: <string> # optional; Qoder BYOC only (see note below)
217
234
vaults: [ <string> ]
218
235
memory_stores: [ <string> ]
219
236
resources: [ DeploymentResource ]
@@ -226,6 +243,8 @@ deployments:
226
243
227
244
`initial_events`is a discriminated union; `schedule.expression` must be a 5-field cron expression.
228
245
246
+
> **Deployment `tunnel` caveat:** Qoder's deployment API does not accept `tunnel_id`, so the tunnel is dropped from the deployment payload and server-side runs execute without it (`validate`/`plan` emits a warning). Use sessions for private-network MCP access; see [Use BYOC environments](../guides/use-byoc-environments.md).
0 commit comments