Egress Proxy Profiles
Attach credentials to a sandbox's outbound requests at the egress boundary so the secret never lives inside the sandbox.
An egress proxy profile modifies a sandbox's outbound HTTP requests at the egress boundary, after traffic leaves the sandbox. Its main job is injecting a credential so agent code can call an authenticated API without ever storing or seeing the secret.
It works alongside an egress network policy:
Egress network policy is the gate. It decides which domains and CIDRs a sandbox can reach. It never modifies requests.
Egress proxy profile is the injector. For an allowed domain, it terminates TLS and adds a secret to the request, as a header, as HTTP basic auth, or as an AWS signature. It never opens the firewall.
Each profile has a name for references and a display_name for its label in the console.
The console lets you set both when you create a profile.
If you omit display_name, it defaults to name.
Existing profiles use their name as the display name.
Tutorial: inject an Anthropic API key for a coding agent
A coding agent runs in a sandbox and must call the Anthropic API, but you do not want the API key inside the sandbox, because the agent's code is untrusted. The agent makes the request with no key in its environment, and the proxy adds the key on the way out.
Store the key as a secret
Pipe the value in on stdin so it never appears in your shell history. Pick the scope that matches who the key belongs to.
Each developer stores their own key.
tektona secret set anthropic-key --scope personal # value read from stdinStore one shared key for the whole project.
tektona secret set anthropic-key --scope project # value read from stdinRun tektona secret set again with the same key to rotate the value — it updates the
secret in place, and running sandboxes pick up the new value within a few seconds.
Create a proxy profile and add the injection rule
Anthropic authenticates with the x-api-key header (not a Bearer token), so the
rule sets that header from the secret.
tektona egress-proxy apply anthropic --scope project
tektona egress-proxy rule add anthropic \
--host api.anthropic.com \
--header 'x-api-key=${secret:anthropic-key}'Because the rule uses a bare secret reference, the shared project profile injects each sandbox owner's personal key when one exists, then falls back to the project key.
Allow api.anthropic.com in the network policy
The profile only injects after traffic is allowed. The built-in tektona/dev
policy already includes common AI APIs, or use tektona/open to allow all
outbound hosts. If you use a custom policy, allow api.anthropic.com in it (see
Egress Network Policies).
Create the sandbox with both attached
tektona sandbox create tektona/desktop \
--egress-network-policy tektona/dev \
--egress-proxy anthropicResult
The agent calls api.anthropic.com with no ANTHROPIC_API_KEY in its
environment. The gateway injects x-api-key at the egress boundary, so the key
never enters the sandbox. To confirm what is active without revealing the value:
tektona sandbox get <id> # lists each handled host and which scope's secret resolvedMore detail
Secret scopes
A secret is stored material referenced by key, at one of three
scopes:
- Personal is the common case: each developer's own API key, used only by sandboxes they own.
- Project is a credential shared with everyone on a project.
- Org is a credential shared across every project in the org.
A bare reference ${secret:KEY} resolves personal, then project, then org. So
one shared project profile can name a single key, and each user's own personal
secret is injected automatically.
Secret references
Rules reference secrets by key, resolved just-in-time at the proxy, so rotation needs no rule change. Use the bare form for normal personal-first resolution, or qualify the scope when a rule must use a specific shared credential.
| Reference | Resolves to |
|---|---|
${secret:anthropic} | default: the user's personal value, then the shared project secret, then the org secret |
${secret:personal:anthropic} | only a value the user scoped to themselves |
${secret:project:anthropic} | the shared project secret |
${secret:org:anthropic} | the org secret |
${secret:shared:anthropic} | shared (project, then org), never a personally scoped value |
Use shared: when a profile must always use the project or org key, for example so a CI
sandbox bills the org account rather than whoever launched it.
A project admin can write a rule that uses an org secret and sends it to any host. The creator of a project becomes its admin. If your org does not trust every member with its org secrets, turn off Allow members to create projects in organization settings. See Roles & Permissions.
Other rule shapes
A rule matches a host and applies one request change:
- Set a header.
--header 'x-api-key=${secret:anthropic}'or--header 'Authorization=Bearer ${secret:anthropic}'. - Use HTTP basic auth. For HTTPS flows that expect
Authorization: Basic ....--basic-secret registry-logintakes the username and the password from onebasicsecret. See Basic credentials. - Sign the request for AWS. See Sign AWS requests.
One header value can use more than one secret. Write a reference for each, and
each gets its own value: --header 'x-api-key=${secret:tenant}:${secret:token}'.
Every rule uses a secret. A rule that adds a fixed value and no secret is refused.
Multiple rules can target the same host — for example one rule injecting an API
key and another setting an Authorization header from a second secret — and all
of them apply to a matching request. Rules that set different headers all apply, so a host-specific rule
adds to a domain-wide one rather than replacing it. Only when two rules set the
same header does one win: the longest path match, then a rule that names the
host over one that wildcards its domain, then the earliest rule.
A rule host is one exact host (api.example.com), or a wildcard over one domain
(*.example.com). Write an international host in either Unicode (bücher.de) or
punycode (xn--bcher-kva.de); both match the same traffic. A host that is not a
valid international domain name is refused when you add the rule.
By default, a rule injects on port 443. To inject on another HTTPS port, list
every port with --port. A rule with --port 7443 injects only on 7443, so add
--port 443 as well when the host serves both:
tektona egress-proxy rule add models \
--host registry.corp.example \
--port 443 --port 7443 \
--header 'Authorization=Bearer ${secret:registry}'The API refuses port 80, because a rule never sends a secret over plain HTTP. It also refuses ports 25, 53, 465, 587 and 6667, because sandbox traffic on them never reaches the proxy. A rule update replaces the ports too: an update with no ports sets 443.
A wildcard sends your secret to every host under the domain
*.example.com credentials api.example.com, staging.example.com, and every
other name under example.com — including hosts you do not control.
The code in the sandbox chooses which host it calls. A wildcard rule therefore
lets that code decide who receives your secret, inside the domain you named. On a
domain that hands subdomains to strangers, that is any of them: a *.amazonaws.com
rule sends the credential to whatever bucket the sandbox asks for, and the bucket
can belong to anybody.
Prefer an exact host. Use a wildcard only where you control every name under the domain.
Tektona refuses *, and refuses a wildcard over a known public suffix:
*.com, *.co.uk, *.pages.dev and *.compute.amazonaws.com all cover hosts
strangers register, and are rejected. That check reads the public suffix list,
which does not name every domain that hands out subdomains. *.amazonaws.com is
accepted and still reaches buckets and instances other people own. The list is
also a snapshot, so a service added to it after your Tektona build is not caught.
The check stops the obvious mistakes. It does not make a wildcard safe.
Sign AWS requests
Every other rule on this page injects a fixed value. AWS cannot be reached that way: it authenticates a request with a SigV4 signature computed over the request's own method, host, path, query and body, so the credential changes with every request and no stored header will do.
A rule that names an AWS region and service makes the proxy compute that signature at the egress boundary. The sandbox never holds the credential — it keeps a placeholder, and the proxy replaces the entire signature on the way out, so a compromised sandbox leaks nothing that works against AWS.
Store the credential first. See AWS credentials.
printf '%s' "$AWS_SECRET_ACCESS_KEY" | \
tektona secret set aws-opensearch --scope project \
--type aws --aws-access-key-id AKIA...Then bind the host to a signing rule:
tektona egress-proxy apply aws-logs --scope project
tektona egress-proxy rule add aws-logs \
--host '*.es.amazonaws.com' \
--aws-region eu-central-1 --aws-service es \
--aws-secret aws-opensearch--aws-service is the AWS service name in the signing scope: es for OpenSearch,
or s3, dynamodb, sts. The IAM policy on the credential decides what the
request may do.
--aws-secret names the secret by its key. Scope-qualify it as org:KEY,
project:KEY or personal:KEY when the same key exists in more than one scope.
Tektona checks the key before it stores the rule: a secret that is not of type
aws cannot sign, and is refused here rather than at the first request.
The profile's page in the console adds the same rule, with the region, the service and the secret as fields.
Your code still needs a credential of its own, because most AWS SDKs refuse to build a request without one. The proxy replaces the whole signature, so that value never reaches AWS. Use the example pair AWS publishes:
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEYKeep the real region and the real endpoint in your code. The proxy corrects the signature, not the address.
An S3 bucket, end to end
# 1. the credential. The secret access key is read from stdin.
printf '%s' "$AWS_SECRET_ACCESS_KEY" | \
tektona secret set aws-files --scope project \
--type aws --aws-access-key-id AKIA...
# 2. a profile, and a rule for the bucket's host
tektona egress-proxy apply aws --scope project
tektona egress-proxy rule add aws \
--host 'my-bucket.s3.eu-central-1.amazonaws.com' \
--aws-region eu-central-1 --aws-service s3 \
--aws-secret aws-files
# 3. a sandbox that uses it. The host must also be allowed by the
# egress network policy — a rule alone does not open the gate.
tektona sandbox create tektona/sandbox-base \
--egress-network-policy tektona/open \
--egress-proxy project/awsThen, inside the sandbox, with the placeholder credential from above:
aws s3 cp ./report.csv s3://my-bucket/report.csv
aws s3 ls s3://my-bucket/Your IAM user needs s3:PutObject and s3:GetObject on arn:aws:s3:::my-bucket/*,
and s3:ListBucket on arn:aws:s3:::my-bucket. The two ARNs differ: object
actions end in /*, and listing acts on the bucket itself.
S3 answers on two host shapes for one signing scope —
<bucket>.s3.<region>.amazonaws.com, which the AWS CLI uses by default, and
s3.<region>.amazonaws.com. A rule binds one host, so add a second rule if your
tool uses path-style addressing.
Four limits apply:
- The credential is a static IAM access key. A temporary credential with a session token is not supported.
- A body up to 10 MiB is held in memory and signed whole. A larger body is
signed per chunk as it streams, up to 5 GiB — the largest object AWS accepts
in one request. Your tool must send the body with a
Content-Length. A body sent withTransfer-Encoding: chunkedhas no length to declare, and the proxy refuses it above 10 MiB. - A recent AWS SDK adds a trailing checksum to an upload and sends the body in
its own
aws-chunkedframes. The proxy signs that body in the mode the SDK chose and forwards the frames unchanged, at any size. The endpoint must behttps: over plainhttpan SDK signs each frame with the placeholder credential, which the proxy cannot replace, and the request is refused. - A signing rule applies last, after every header rule that matches the same request, because the signature covers those headers.
A rule can also scope to a path prefix with --path. A request to that host on a
path no rule covers still goes through, and carries no injected value. The request
path reaches the host exactly as your tool sent it, so an address that contains an
encoded character, such as GitLab's gitlab-org%2Fcli, arrives unchanged.
Git credentials use the dedicated Git Repositories flow, not proxy-profile rules.
Removing a rule
tektona egress-proxy show <profile> lists each rule with its id. Remove a rule
by id:
tektona egress-proxy show anthropic
tektona egress-proxy rule rm anthropic <rule-id>What the proxy can inspect
The proxy can only read and credential traffic it can understand. It reads plain HTTP and the TLS handshake on every TCP port. It decrypts only TLS to a host that a rule binds, on a port that the rule lists.
- Inspected and injectable. HTTPS over TCP to a host that a rule binds, on a port that the rule lists (443 by default). The proxy terminates TLS with the per-node CA and injects into the decrypted HTTP request. It serves HTTP/1.1 and HTTP/2 here, and injects a request header, applies HTTP basic auth, or signs the request for AWS. These are the only request changes a rule can make.
- Passed through, not credentialed. Plain HTTP on port 80, even to a host a
rule binds. A rule never adds its value to a cleartext request, which would put
your secret on the wire in the clear. The request reaches the server unchanged,
so an ordinary
http://→https://redirect works and the request that follows it is credentialed. Usehttps://for every address a rule binds. - Passed through, not inspected. Any request to a host that no rule binds stays end-to-end TLS and is never decrypted, so it carries no injected credential. Such traffic still has to pass the egress network policy to leave at all.
- Never credentialed. Only HTTPS on a port that a rule lists can carry an
injected credential. TCP on other ports passes the egress network policy check,
which reads the TLS server name or HTTP
Host, but it is never decrypted. UDP, such as QUIC and HTTP/3, never reaches the proxy. The proxy does not read other protocols, for example SSH or a database protocol on port 443.
HTTP/3 falls back to TCP for injected hosts
The gateway refuses HTTP/3 (QUIC) to a host that a rule binds. The client then retries over HTTPS on TCP, where the proxy injects the credential. If a tool does not fall back, disable HTTP/3 for that host. HTTP/3 on a port other than 443 is not refused and carries no credential, so disable HTTP/3 for such a host too.
CA trust in the sandbox
To inject a credential, Tektona terminates TLS at the egress boundary for the specific hosts a profile or git credential binds. Those hosts are served a certificate signed by a per-node Tektona CA. Every other host is passed through untouched and keeps its own real public certificate.
So a sandbox needs to trust both the Tektona CA, for the injected hosts, and
the normal public certificate authorities, for everything else such as cloning a
public github.com repository. Tektona handles this for you. At sandbox start it
installs a combined trust bundle made of your image's public roots plus the
Tektona CA, and points the standard TLS variables at it (SSL_CERT_FILE,
CURL_CA_BUNDLE, GIT_SSL_CAINFO, REQUESTS_CA_BUNDLE, and
NODE_EXTRA_CA_CERTS). As a result curl, git, Python requests, and Node
verify both injected and ordinary HTTPS with no setup.
Some runtimes ship their own trust store and ignore the system one. Java is the usual example. For those, import the live CA at startup, which also stays correct across rotation:
tektonactl ca cert | keytool -importcert -alias tektona \
-cacerts -storepass changeit -nopromptImport at runtime, never bake the CA into an image
The CA lives inside the running sandbox and it rotates. A copy baked into a custom image would be stale after rotation. Always read the live cert at boot. Cert-pinned apps and statically-linked binaries with embedded roots cannot accept the CA, so calls to an intercepted host fail with a loud TLS error. Tektona does not silently send the request without the credential.
Attaching a profile
A profile affects a sandbox only when attached by the platform, never self-attached by the in-sandbox agent.
- A project can have a default profile (created with
--default), auto-applied to every sandbox. - Sandbox creation can attach or override a profile with
--egress-proxy <name>(--egress-proxy-profileis the long-form alias).
The reference prefix is a scope keyword: a bare <name> (or project/<name>)
is a profile in the sandbox's project, and org/<name> is a profile in its
organization. A bare name never falls back to the org scope — use org/<name>
for a shared profile.
Agents cannot grant themselves more reach or more credentials, which is how a deploy step can get a token the agent sandbox never receives.
Attaching to an existing sandbox
A sandbox created without a profile — or one that should switch to a different profile — doesn't need to be recreated. Attach, switch, or detach on a running sandbox and the change applies immediately, without a restart:
tektona sandbox egress-proxy set <sandbox-id> anthropic # attach or switch
tektona sandbox egress-proxy set <sandbox-id> org/shared # switch to an org profile
tektona sandbox egress-proxy unset <sandbox-id> # detachset replaces the current attachment — a sandbox has at most one profile.
After unset the sandbox keeps its egress network policy; requests to
previously injected hosts still leave (policy permitting) but carry no
credential and are no longer TLS-intercepted.
The sandbox must be running: both commands confirm the change is active on the
sandbox's node before they succeed, and a paused sandbox must be resumed before
its profile can change. If the node can't confirm in time (for example, it is
temporarily unreachable), the change is still saved and the command fails with
an error saying so — the profile applies automatically once the node is
reachable again; re-run the command to confirm. unset on a sandbox with no
attached profile returns an error instead of silently succeeding.
Profile changes apply to the selected sandbox only. Other sandboxes on the node keep their current profiles. A failed confirmation does not remove the saved profile change.
Security model
Edge injection is designed to fail closed:
- Injected headers overwrite sandbox-set ones. The sandbox cannot smuggle a competing value for the same header.
- A credential only flows to its matched host. The proxy requires the
handshake SNI and the request
Hostto agree, and re-resolves the upstream with SSRF and internal-CIDR checks, so an agent cannot redirect an authenticated request to capture the credential. - The value is fetched just-in-time. The proxy resolves the secret at request time, caches it briefly (at most 60s), and fails closed rather than serving a stale value.
- Near-instant revocation. Rotating, deleting, or detaching a secret, or removing a member, evicts cached values within seconds.