canonical: https://jentic.com/apis/googleapis.com/cloudshell # Google Cloud Shell API The Cloud Shell API lets users start, configure, and connect to interactive shell sessions running on Google-managed VMs preloaded with the gcloud SDK and common developer tooling. Programmatic callers can fetch the user's environment, authorize an SSH session, and manage the public keys used to connect from local clients. It is most often used to embed a one-click shell experience into developer tools, training apps, and onboarding flows that need a real Linux environment without provisioning infrastructure. ## For AI agents Start, authorize, and manage a user's Google Cloud Shell environment, including SSH public keys for remote access. Lets agents drive a managed Linux session attached to the user's GCP identity. ## Scope Does not provision custom VMs, execute shell commands directly, or persist user files outside the environment - use for managing the lifecycle and SSH access of Google Cloud Shell sessions only. ## Capabilities - Start a user's Cloud Shell environment and poll until it is RUNNING - Authorize a Cloud Shell session with short-lived gcloud credentials - Add and remove SSH public keys attached to the environment - Cancel an in-flight start or authorize operation - Get the current state of the Cloud Shell environment ## Use cases ### One-Click Tutorial Sandboxes Embed a Cloud Shell session into a learning app so users land in a configured Linux environment with gcloud installed and authenticated. The API starts the environment on demand and authorize returns short-lived credentials so the session can run gcloud commands against the user's own project, eliminating the need to ship a virtual machine image with each tutorial. Example prompt: Call environments.start on users/me/environments/default and poll the operation until state is RUNNING, then return the SSH connection details ### Remote SSH Key Management Manage the SSH public keys attached to a user's Cloud Shell environment so that local IDEs and CI runners can connect into the same managed VM. The API exposes addPublicKey and removePublicKey operations so devops teams can rotate keys on a schedule without users opening the Cloud Shell web UI. Example prompt: Add a fresh ed25519 public key to users/me/environments/default and remove any keys older than 90 days ### Headless Cloud Shell Sessions for Scripts Spin up a Cloud Shell environment from a script, run a sequence of commands using the authorized credentials, and tear down at the end. This pattern is useful when you want a script to inherit the user's gcloud context without bundling service account keys, and the API's start/authorize/cancel surface gives enough lifecycle control for headless use. Example prompt: Start the user's Cloud Shell environment, call authorize to get short-lived gcloud credentials, run gcloud projects list, and cancel the start operation when finished ### Agent-Driven Developer Onboarding An AI assistant that helps developers join a new project can spin up the user's Cloud Shell, push the right SSH key, and walk them through their first commands. Through Jentic the agent searches for 'start cloud shell environment', loads the schema, and avoids hardcoding the Cloud Shell resource paths. Example prompt: Use Jentic to start users/me/environments/default and add the agent's generated public key so a follow-up SSH command can connect ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /v1/{+name}:start | Start the user's Cloud Shell environment | | POST | /v1/{+name}:authorize | Authorize the environment with short-lived credentials | | POST | /v1/{+environment}:addPublicKey | Add an SSH public key to the environment | | POST | /v1/{+environment}:removePublicKey | Remove an SSH public key from the environment | | POST | /v1/{+name}:cancel | Cancel an in-flight start or authorize operation | ## Key resources - **Environments** — Get, start, authorize, and manage the user's Cloud Shell environment - **Public Keys** — Add and remove SSH public keys attached to the environment - **Operations** — Track and cancel long-running start and provisioning operations ## Why Jentic - **Setup:** Wiring the Cloud Shell API by hand means setting up Google OAuth 2.0, minting short-lived tokens against the cloud-platform scope, and addressing each environment by resource name against cloudshell.googleapis.com yourself. Through Jentic you install once, import the Cloud Shell API from the API Directory, store the OAuth credential once, and your agent calls it. - **Permission scoping:** Cloud Shell puts the environment resource name in the URL path (/v1/{+name}:start, /v1/{+environment}:addPublicKey), so a rule can pin your agent to one environment: it can start it and add public keys there and nothing else. You choose the operations it may call, so removePublicKey or cancel are not included unless you add them. - **Credential handling:** Your Cloud Shell OAuth credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'start a Cloud Shell environment' or 'add an SSH key to Cloud Shell', and Jentic returns the matching Cloud Shell operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Compute Engine API** — Provisions full custom VMs instead of a managed shell environment - **Identity and Access Management (IAM) API** — Manages the GCP roles a Cloud Shell user can exercise from inside the session - **Cloud Resource Manager API** — Provides the project context a Cloud Shell session typically operates against ## FAQ ### What authentication does the Cloud Shell API use? It uses Google OAuth 2.0 with the https://www.googleapis.com/auth/cloud-platform scope. Through Jentic the OAuth refresh token lives in your Jentic One instance and the agent only ever sees a short-lived access token at execution time. ### Can I start a user's Cloud Shell environment with the API? Yes. Call POST on /v1/{name}:start with the environment resource (typically users/me/environments/default). The endpoint returns a long-running operation that resolves once the VM is RUNNING and ready to accept SSH connections. ### What are the rate limits for the Cloud Shell API? Cloud Shell environments are rate-limited per user, with restrictions on how often start can be invoked and a weekly cap on session hours per user. Programmatic callers should poll the get endpoint with backoff rather than retrying start in a tight loop. ### How do I add an SSH key through Jentic? Search Jentic for 'add ssh key to cloud shell', load the environments.addPublicKey schema, and execute the call against /v1/{environment}:addPublicKey with the key in OpenSSH format. Jentic returns the schema so the agent does not need to memorise the request body. ### Is the Cloud Shell API free? Cloud Shell is included free for users with an active Google account, subject to weekly usage quotas. The API has no per-call charge - you only consume the user's underlying Cloud Shell allocation. ### Can the API run shell commands directly? No. The API only manages the lifecycle of the environment and its SSH keys. Once the environment is RUNNING and authorized, your client connects via SSH to execute commands. ### Can I limit what my agent is allowed to do with the Cloud Shell API? Yes. Because you run Jentic One yourself, your own rules decide which Cloud Shell operations and credentials the agent may use. Since the environment resource name sits in the URL path (for example /v1/{+name}:start and /v1/{+environment}:addPublicKey), you can pin the agent to a single environment and grant only the calls you want, such as letting it start the environment and add an SSH public key. Operations like removePublicKey or cancel stay unavailable unless you explicitly add them, and the stored OAuth credential is injected at execution time so the agent never sees it.