Remote debugging

When your software runs in a customer's cloud, debugging usually means screenshots, copy-pasted logs, and Zoom calls. alien debug replaces that. It opens a secure channel into a customer's deployment and runs a local command — or an interactive shell — against it, using credentials the manager hands out just for that session.

Nothing about the customer's network changes: there are no inbound ports, no VPN, and no shared cloud access. The deployment behaves like another region in your own cloud.

# Request access, wait for the customer to approve it, then run the command
alien debug acme/prod --request-access -- aws sts get-caller-identity
alien debug acme/prod --request-access -- gcloud projects list
alien debug acme/prod --request-access -- kubectl get pods -n my-product

# Reuse an approved access request
alien debug acme/prod --access-request ar_123 -- kubectl get pods -n my-product

# No command drops you into a shell with the env already set
alien debug acme/prod --access-request ar_123

A deployment can be referenced by ID (dep_...), by name, or as <group>/<name>.

Get approvalCopy Anchor Link

A debug session needs an access request that the customer approved for that deployment and tool. The tools are kubectl, aws, gcloud, and az. If you pass no access request, the manager refuses the session with DEBUG_ACCESS_REQUEST_REQUIRED.

--request-access creates the request for the tool in your command, waits for approval, and starts the session. For kubectl, it scopes the request to the namespace in -n or --namespace. For a cloud CLI, add --access-cloud-scope <account-or-project> to scope the request to one account, project, or subscription. --access-duration sets the requested window. The default is 30m.

You can also create the request first and pass its ID:

alien access-requests create --deployment acme/prod \
  --debug-tool kubectl --debug-namespace my-product --duration 30m

alien access-requests wait ar_123

alien debug acme/prod --access-request ar_123 -- kubectl get pods -n my-product

The customer approves on their side. For a Kubernetes deployment, the CLI prints the kubectl patch command that the customer runs in the cluster. No Alien command approves a request. A request lasts at most six hours, and an approval never extends past the requested duration.

These rules limit what an approved request allows:

• Only its creator can use it. A request that you created works for you. A request that an API key created works for that API key. If you pass another person's request ID, the manager refuses the session with a debug session can only use a grant its caller requested.
• The scope holds for every call. A kubectl request scoped to one namespace refuses other namespaces and cluster-scoped resources such as nodes. A cloud request scoped to one account refuses a deployment in another account.
• The session ends with the approval. The manager checks the request on every call it forwards and closes the tunnel when the approval window ends. To continue, request access again.

How it worksCopy Anchor Link

alien debug asks the manager for a short-lived debug session, then runs your command with the environment that session returns. Two things make it safe:

• Least-privilege identity. The session acts as the deployment's own scoped identity — the same one Alien uses to manage that environment (see Impersonation). It can touch the deployment's isolated area and nothing else. The customer controls what that identity is allowed to do, and approves each session.
• Ephemeral credentials. Any credential files (like a kubeconfig) are written to a per-session temp directory with 0600 permissions and deleted when the command exits. Nothing is left on disk.

Under the hood the channel uses whichever deployment model the customer is on:

• Push. The CLI runs a loopback proxy on 127.0.0.1 and points the cloud CLI at it (AWS_ENDPOINT_URL and the GCP/Azure equivalents). Requests tunnel to the manager over an authenticated WebSocket, where they're re-signed with the impersonated identity and forwarded to the cloud. Your aws command thinks it's talking to AWS; it's really talking through Alien.
• Pull. A lightweight agent inside the environment calls out over HTTPS. Same result, no inbound connection.

Debug a Remote Operator installationCopy Anchor Link

A Remote Operator installation uses the pull model. The operator dials out to Alien and forwards each kubectl request to the cluster's API server with its own ServiceAccount token. The session has the operator's Kubernetes permissions and no more.

Those permissions are list on Deployments, StatefulSets, DaemonSets, pods, events, and pod metrics, plus what the enabled operations declare. See Kubernetes permissions.

# Works on every installation: the operator can list pods.
alien debug acme/prod --access-request ar_123 -- kubectl get pods -n my-product

# Fails with "forbidden" unless an enabled operation declares list on configmaps.
alien debug acme/prod --access-request ar_123 -- kubectl get configmaps -n my-product

To allow more, enable an operation that declares the rule, then apply the permission change to the installation.

Each kubectl request returns one buffered response. Commands that stream are not supported: kubectl logs -f, exec, port-forward, and cp. A session lasts at most 30 minutes, or until the approval ends if that is sooner.

Cloud CLIs work on a Remote Operator installation too. The operator signs each request with its own workload identity, so the session has the cloud permissions you granted to the operator in Connect cloud APIs.

Scope and auditingCopy Anchor Link

Debug sessions are scoped to operating the deployment, not reading customer data. They run as the management identity, or as the operator on a Remote Operator installation. They are bounded by the permissions the customer granted and leave an audit trail. When you need to inspect data on demand instead, reach for a remote command, which runs inside the environment and returns only what you ask for.

What's nextCopy Anchor Link