0
# Google Cloud Shell
1

2
Google Cloud Shell API client library for programmatic management of Cloud Shell environments. Each user has at least one environment (ID "default") consisting of a Docker image and persistent home directory that remains across sessions. This library enables starting environments, managing SSH keys, and handling OAuth authorization.
3

4
## Package Information
5

6
- **Package Name**: google-cloud-shell
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install google-cloud-shell`
10

11
## Core Imports
12

13
```python
14
from google.cloud.shell import CloudShellServiceClient, CloudShellServiceAsyncClient
15
```
16

17
Import specific types:
18

19
```python
20
from google.cloud.shell import (
21
    Environment,
22
    GetEnvironmentRequest,
23
    StartEnvironmentRequest,
24
    AddPublicKeyRequest,
25
    CloudShellErrorDetails
26
)
27
```
28

29
## Basic Usage
30

31
```python
32
from google.cloud.shell import CloudShellServiceClient
33

34
# Initialize client
35
client = CloudShellServiceClient()
36

37
# Get environment information
38
environment = client.get_environment(
39
    name="users/me/environments/default"
40
)
41
print(f"Environment state: {environment.state}")
42
print(f"SSH connection: {environment.ssh_username}@{environment.ssh_host}:{environment.ssh_port}")
43

44
# Start environment (long-running operation)
45
operation = client.start_environment(
46
    name="users/me/environments/default"
47
)
48
response = operation.result()  # Wait for completion
49
print(f"Started environment: {response.environment.name}")
50
```
51

52
## Architecture
53

54
The Google Cloud Shell API follows Google Cloud client library patterns:
55

56
- **Client Classes**: Synchronous (`CloudShellServiceClient`) and asynchronous (`CloudShellServiceAsyncClient`) clients
57
- **Long-Running Operations**: Most mutating operations return `operation.Operation` objects that can be polled for completion
58
- **Resource Paths**: Structured resource names following the pattern `users/{owner}/environments/{environment_id}`
59
- **Authentication**: Uses Google Auth library with service account or user credentials
60
- **Transport Options**: Support for gRPC and REST transports
61

62
## Capabilities
63

64
### Client Management
65

66
Client initialization, configuration, and lifecycle management for both synchronous and asynchronous operations.
67

68
```python { .api }
69
class CloudShellServiceClient:
70
    def __init__(
71
        self,
72
        *,
73
        credentials: Optional[ga_credentials.Credentials] = None,
74
        transport: Optional[Union[str, CloudShellServiceTransport, Callable]] = None,
75
        client_options: Optional[Union[ClientOptions, dict]] = None,
76
        client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
77
    ) -> None: ...
78

79
class CloudShellServiceAsyncClient:
80
    def __init__(
81
        self,
82
        *,
83
        credentials: Optional[ga_credentials.Credentials] = None,
84
        transport: Optional[Union[str, CloudShellServiceTransport, Callable]] = "grpc_asyncio",
85
        client_options: Optional[ClientOptions] = None,
86
        client_info: gapic_v1.client_info.ClientInfo = DEFAULT_CLIENT_INFO,
87
    ) -> None: ...
88
```
89

90
[Client Management](./clients.md)
91

92
### Environment Operations
93

94
Core operations for managing Cloud Shell environments including getting environment details, starting environments, and handling OAuth authorization.
95

96
```python { .api }
97
def get_environment(
98
    self,
99
    request: Optional[Union[cloudshell.GetEnvironmentRequest, dict]] = None,
100
    *,
101
    name: Optional[str] = None,
102
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
103
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
104
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
105
) -> cloudshell.Environment: ...
106

107
def start_environment(
108
    self,
109
    request: Optional[Union[cloudshell.StartEnvironmentRequest, dict]] = None,
110
    *,
111
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
112
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
113
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
114
) -> operation.Operation: ...
115

116
def authorize_environment(
117
    self,
118
    request: Optional[Union[cloudshell.AuthorizeEnvironmentRequest, dict]] = None,
119
    *,
120
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
121
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
122
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
123
) -> operation.Operation: ...
124
```
125

126
[Environment Operations](./environments.md)
127

128
### SSH Key Management
129

130
Operations for managing SSH public keys associated with Cloud Shell environments, enabling secure SSH connections.
131

132
```python { .api }
133
def add_public_key(
134
    self,
135
    request: Optional[Union[cloudshell.AddPublicKeyRequest, dict]] = None,
136
    *,
137
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
138
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
139
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
140
) -> operation.Operation: ...
141

142
def remove_public_key(
143
    self,
144
    request: Optional[Union[cloudshell.RemovePublicKeyRequest, dict]] = None,
145
    *,
146
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
147
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
148
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = (),
149
) -> operation.Operation: ...
150
```
151

152
[SSH Key Management](./ssh-keys.md)
153

154
## Types
155

156
### Core Environment Type
157

158
```python { .api }
159
class Environment(proto.Message):
160
    """A Cloud Shell environment combining Docker image and persistent home directory."""
161
    
162
    name: str                           # Immutable resource name: users/{owner}/environments/{id}
163
    id: str                            # Output only environment identifier
164
    docker_image: str                  # Required immutable Docker image path
165
    state: Environment.State           # Output only current execution state
166
    web_host: str                      # Output only HTTPS/WSS connection host
167
    ssh_username: str                  # Output only SSH username
168
    ssh_host: str                      # Output only SSH connection host
169
    ssh_port: int                      # Output only SSH connection port
170
    public_keys: MutableSequence[str]  # Output only associated public keys
171

172
class State(proto.Enum):
173
    STATE_UNSPECIFIED = 0  # Unknown state
174
    SUSPENDED = 1          # Not running, can be started
175
    PENDING = 2           # Starting but not ready
176
    RUNNING = 3           # Running and ready for connections
177
    DELETING = 4          # Being deleted
178
```
179

180
### Error Handling
181

182
```python { .api }
183
class CloudShellErrorDetails(proto.Message):
184
    """Cloud Shell-specific error information."""
185
    
186
    code: CloudShellErrorDetails.CloudShellErrorCode
187

188
class CloudShellErrorCode(proto.Enum):
189
    CLOUD_SHELL_ERROR_CODE_UNSPECIFIED = 0  # Unknown error
190
    IMAGE_UNAVAILABLE = 1                   # Docker image unavailable
191
    CLOUD_SHELL_DISABLED = 2               # Cloud Shell disabled by admin
192
    TOS_VIOLATION = 4                      # Terms of Service violation
193
    QUOTA_EXCEEDED = 5                     # Weekly quota exhausted
194
    ENVIRONMENT_UNAVAILABLE = 6            # Environment unavailable
195
```