Containers subclient—cloud containers via sprites.dev. Run code, deploy agents, manage files, and execute commands remotely.

Containers Subclient

The client.containers subclient lets you manage cloud containers via sprites.dev—remote environments for running code, deploying agents, and managing files. List containers, read and write files, execute commands, and sync directories.

Methods

Method	Signature	Description
`list`	`() => Promise<Container[]>`	List all your containers
`remove`	`(id: string) => Promise<void>`	Remove a container
`ls`	`(id, path?) => Promise<FileEntry[]>`	List files in a container
`read`	`(id, path) => Promise<string>`	Read file content
`write`	`(id, path, content) => Promise<void>`	Write file content
`mkdir`	`(id, path) => Promise<void>`	Create a directory
`rm`	`(id, path) => Promise<void>`	Remove a file or directory
`rsync`	`(id, localDir, remoteDir) => Promise<void>`	Sync local dir to container
`exec`	`(id, command) => Promise<ExecResult>`	Execute a command
`shell`	`(id) => ShellSession`	Interactive shell session

list()

list(): Promise<Container[]>

Returns all containers for the authenticated user.

const containers = await client.containers.list();
containers.forEach(c => console.log(`${c.id}: ${c.name || 'unnamed'}`));

remove(id)

remove(id: string): Promise<void>

Removes (destroys) a container by ID.

await client.containers.remove('container-uuid');

File Operations

ls(id, path?)

ls(id: string, path?: string): Promise<FileEntry[]>

Lists files and directories at the given path. Omit path or use / for the root.

const entries = await client.containers.ls(container.id, '/app');
entries.forEach(e => console.log(e.name, e.type));

read(id, path)

read(id: string, path: string): Promise<string>

Reads file content as a string.

const content = await client.containers.read(container.id, '/app/index.ts');

write(id, path, content)

write(id: string, path: string, content: string): Promise<void>

Writes content to a file. Creates parent directories if needed.

await client.containers.write(container.id, '/app/hello.ts', 'console.log("hi");');

mkdir(id, path)

mkdir(id: string, path: string): Promise<void>

Creates a directory at the given path.

await client.containers.mkdir(container.id, '/app/src/utils');

rm(id, path)

rm(id: string, path: string): Promise<void>

Removes a file or directory.

await client.containers.rm(container.id, '/app/old-file.ts');

rsync(id, localDir, remoteDir)

rsync(id: string, localDir: string, remoteDir: string): Promise<void>

Syncs a local directory to a path inside the container. Useful for deploying code or assets.

await client.containers.rsync(container.id, './dist', '/app/dist');

exec(id, command)

exec(id: string, command: string): Promise<ExecResult>

Executes a command in the container. Returns ExecResult with stdout, stderr, and exit code.

const result = await client.containers.exec(container.id, 'npm install');
console.log(result.stdout, result.stderr, result.exitCode);

shell(id)

shell(id: string): ShellSession

Starts an interactive shell session. Use for REPL-style interaction, debugging, or manual operations.

const session = client.containers.shell(container.id);
// Send commands and receive output; close when done

The shell() method returns an interactive session. Exact usage depends on the SDK implementation—check the package for stream APIs and cleanup.

Use Cases

Run scripts, build steps, or tests in an isolated cloud environment. Use write() to stage files, exec() to run commands like npm run build, and read() to fetch output.

Deploy AI agents or services into containers. Use rsync() to push your codebase, exec() to start the agent process, and read() to inspect logs or state.

Manage remote files as if they were local. List directories with ls(), edit with read()/write(), and organize with mkdir()/rm().

Code Examples

import { PUClient } from 'pu-client';

const client = new PUClient({ apiKey: process.env.PU_API_KEY! });

const containers = await client.containers.list();
const container = containers[0];

await client.containers.write(container.id, '/app/script.ts', `
  console.log("Hello from container");
`);

const result = await client.containers.exec(container.id, 'npx tsx /app/script.ts');
console.log(result.stdout);

import { PUClient } from 'pu-client';

const client = new PUClient({ apiKey: process.env.PU_API_KEY! });

const containers = await client.containers.list();
const container = containers[0];

await client.containers.rsync(container.id, './my-app', '/app');
const result = await client.containers.exec(container.id, 'cd /app && npm install && npm start');
console.log(result.exitCode);

Full Workflow

1. List containers

const containers = await client.containers.list();

2. Create or select a container

Containers are typically created via the sprites.dev platform or API. Use list() to find an existing one.

3. Manage files

await client.containers.mkdir(container.id, '/app');
await client.containers.write(container.id, '/app/index.js', '...');
const files = await client.containers.ls(container.id, '/app');

4. Run commands

const out = await client.containers.exec(container.id, 'node /app/index.js');

5. Clean up

await client.containers.remove(container.id);