Installation¶

Rayito has two SDKs with the same surface, Python and TypeScript, and a CLI in each one, with the same commands. Install the SDK for your application's language and, to set up the account, the CLI of either one.

The SDK¶

PythonTypeScript

pip install rayito             # or: uv add rayito

Python ≥ 3.11. Runtime dependencies: grpcio, protobuf and boto3. The SDK ships a synchronous tree (Sandbox) and an asynchronous one (AsyncSandbox) with the same surface.

pnpm add rayito                # or: npm i rayito / yarn add rayito / bun add rayito

Node ≥ 20. The package ships ESM and CommonJS with their types, and the E2B shim at rayito/e2b. Everything is asynchronous. await using needs TypeScript ≥ 5.2 with "lib": ["ES2022", "ESNext.Disposable"].

The CLI¶

The rayito CLI publishes the image, diagnoses the account and operates sandboxes. There is one per SDK, with the same surface (CLI):

PythonTypeScript

It is an extra of the Python package:

pip install "rayito[cli]"          # or: uv tool install "rayito[cli]"
rayito --help

To run it without installing: uvx --from "rayito[cli]" rayito doctor.

It ships in the npm package, with no extras:

npx rayito --help                  # or: npm install --global rayito

If you install both, the first one on the PATH wins; rayito --version says which one answers.

Optional extras¶

None of this is needed to get started.

For	Python	TypeScript
The `rayito` CLI	`pip install "rayito[cli]"`	(included in the package: `npx rayito`)
The MCP server (MCP server)	`pip install "rayito[mcp]"`	`npm i @modelcontextprotocol/server zod`
OpenTelemetry traces (OpenTelemetry)	`pip install "rayito[otel]" opentelemetry-sdk`	`npm i @opentelemetry/api @opentelemetry/sdk-trace-base`
Secrets Manager secrets (Secrets)	(included: uses `boto3`)	`npm i @aws-sdk/client-secrets-manager`
Secret gateway and agent in the sandbox (Secret gateway, Agent in the sandbox)	(included: uses `boto3`)	`npm i @aws-sdk/client-secrets-manager`
Metadata index in DynamoDB (Index)	(included: uses `boto3`)	`npm i @aws-sdk/client-dynamodb`
Events and webhooks (Events and webhooks)	(included: uses `boto3`)	`npm i @aws-sdk/client-dynamodb @aws-sdk/client-secrets-manager`
Optional stacks from code (Optional stacks)	(included: uses `boto3`)	`npm i @aws-sdk/client-cloudformation`
Logs of a failed `Template.build()` build (Templates)	(included: uses `boto3`)	`npm i @aws-sdk/client-cloudwatch-logs`
EFS volumes, experimental (EFS volumes)	(included: uses `boto3`)	`npm i @aws-sdk/client-efs @aws-sdk/client-ec2`
Quotas and cost of the management dashboard (Management dashboard)	(included: uses `boto3`)	`npm i @aws-sdk/client-service-quotas @aws-sdk/client-cost-explorer`
Custom domain, experimental (Custom domain)	`pip install "rayito[custom-domain]"`	`npm i @aws-sdk/client-cloudformation @aws-sdk/client-cloudfront-keyvaluestore @aws-sdk/signature-v4a`
Deploying an agent to AgentCore (Deploy to AgentCore)	(included: uses `boto3`)	`npm i @aws-sdk/client-cloudformation @aws-sdk/client-codebuild @aws-sdk/client-ecr @aws-sdk/client-bedrock-agentcore @aws-sdk/client-bedrock-agentcore-control @aws-sdk/client-cloudwatch-logs`
The `RayitoAgent` and `RayitoMicrovmImage` CDK constructs (Deploy with CDK)	`pip install "rayito[cdk]"` (synthesis also needs Node ≥ 20, for jsii)	`npm i aws-cdk-lib constructs` (imported from `rayito/cdk`)

In TypeScript those packages are optional peerDependencies: the SDK only loads them when you enable the feature. If you enable it without installing them, the first call throws InvalidArgumentError with the install command. The CDK ones are the exception: rayito/cdk imports aws-cdk-lib and constructs when it loads, and rayito and its other entry points never load them.

Credentials¶

The SDK uses the standard AWS credential chain: boto3's in Python and the AWS SDK v3's in TypeScript. With a profile:

export AWS_PROFILE=<your-profile> AWS_REGION=us-east-1

With AWS IAM Identity Center (SSO), sign in first with aws sso login --profile <your-profile>; when the session expires, the SDK raises an authentication error (see Troubleshooting).

Check the installation¶

PythonTypeScript

python -c "import rayito; print(rayito.__version__)"

node --input-type=module -e 'import { VERSION } from "rayito"; console.log(VERSION)'

Running the examples¶

The examples in this documentation are complete programs: save them to a file and run it.

PythonTypeScript

python first.py

Nothing else is needed: the example with asyncio.run(...) runs this way too.

The examples use top-level await and await using, so the project has to be an ES module with a tsconfig.json that understands them. Once per project:

npm init -y
npm pkg set type=module            # "type": "module" in package.json
pnpm add rayito                    # or: npm i rayito
pnpm add -D tsx typescript @types/node

And a minimal tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "ESNext.Disposable"],
    "module": "nodenext",
    "types": ["node"],
    "strict": true,
    "skipLibCheck": true
  }
}

Save the example as first.ts and run it with tsx, which runs TypeScript without compiling:

npx tsx first.ts
npx tsc --noEmit                   # optional: check the types

If you prefer to compile, npx tsc and then node first.js work with the same tsconfig.json.

Next step¶

Set up AWS: the rayito-base image and the permissions in your account.