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 stdin

Run 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 anthropic

Result

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 resolved

More 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.

ReferenceResolves 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-login takes the username and the password from one basic secret. 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/bPxRfiCYEXAMPLEKEY

Keep 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/aws

Then, 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 with Transfer-Encoding: chunked has 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-chunked frames. The proxy signs that body in the mode the SDK chose and forwards the frames unchanged, at any size. The endpoint must be https: over plain http an 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. Use https:// 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 -noprompt

Import 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-profile is 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>             # detach

set 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 Host to 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.

Next

On this page