@agentuity/cli 0.1.9 → 0.1.10

package/src/cmd/cloud/sandbox/get.ts

@@ -1,9 +1,10 @@
 import { z } from 'zod';
 import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
-import { createSandboxClient } from './util';
+import { cacheSandboxRegion } from './util';
 import { getCommand } from '../../../command-prefix';
 import { sandboxGet } from '@agentuity/server';
+import { getGlobalCatalystAPIClient } from '../../../config';
 
 const SandboxResourcesSchema = z.object({
 	memory: z.string().optional().describe('Memory limit (e.g., "512Mi", "1Gi")'),
@@ -35,7 +36,7 @@ export const getSubcommand = createCommand({
 	aliases: ['info', 'show'],
 	description: 'Get information about a sandbox',
 	tags: ['read-only', 'fast', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	idempotent: true,
 	examples: [
 		{
@@ -51,11 +52,16 @@ export const getSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, options, auth, region, logger, orgId } = ctx;
-		const client = createSandboxClient(logger, auth, region);
+		const { args, options, auth, logger, orgId, config } = ctx;
+		const client = await getGlobalCatalystAPIClient(logger, auth, config?.name);
 
 		const result = await sandboxGet(client, { sandboxId: args.sandboxId, orgId });
 
+		// Cache the region for future lookups
+		if (result.region) {
+			await cacheSandboxRegion(config?.name, args.sandboxId, result.region);
+		}
+
 		if (!options.json) {
 			const statusColor =
 				result.status === 'running'

package/src/cmd/cloud/sandbox/index.ts

@@ -56,7 +56,7 @@ export const command = createCommand({
 		uploadSubcommand,
 		envSubcommand,
 	],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 });
 
 export default command;

package/src/cmd/cloud/sandbox/list.ts

@@ -3,7 +3,7 @@ import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
 import { getCommand } from '../../../command-prefix';
 import { sandboxList } from '@agentuity/server';
-import { createSandboxClient } from './util';
+import { getGlobalCatalystAPIClient } from '../../../config';
 import type { SandboxStatus } from '@agentuity/core';
 
 const SandboxInfoSchema = z.object({
@@ -30,7 +30,7 @@ export const listSubcommand = createCommand({
 	aliases: ['ls'],
 	description: 'List sandboxes with optional filtering',
 	tags: ['read-only', 'slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	optional: { project: true },
 	idempotent: true,
 	pagination: {
@@ -74,8 +74,8 @@ export const listSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { opts, options, auth, project, region, logger, orgId } = ctx;
-		const client = createSandboxClient(logger, auth, region);
+		const { opts, options, auth, project, logger, orgId, config } = ctx;
+		const client = await getGlobalCatalystAPIClient(logger, auth, config?.name);
 
 		const projectId = opts.projectId || project?.projectId;
 

package/src/cmd/cloud/sandbox/ls.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
-import { createSandboxClient } from './util';
+import { getSandboxRegion, createSandboxClient } from './util';
 import { getCommand } from '../../../command-prefix';
 import { sandboxListFiles } from '@agentuity/server';
 
@@ -23,7 +23,7 @@ export const lsSubcommand = createCommand({
 	aliases: ['lsf'],
 	description: 'List files in a sandbox directory',
 	tags: ['slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('cloud sandbox files sbx_abc123'),
@@ -61,7 +61,8 @@ export const lsSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, opts, options, auth, region, logger, orgId } = ctx;
+		const { args, opts, options, auth, config, logger, orgId } = ctx;
+		const region = await getSandboxRegion(logger, auth, config?.name, args.sandboxId, orgId);
 		const client = createSandboxClient(logger, auth, region);
 
 		const result = await sandboxListFiles(client, {

package/src/cmd/cloud/sandbox/mkdir.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
-import { createSandboxClient } from './util';
+import { createSandboxClient, getSandboxRegion } from './util';
 import { getCommand } from '../../../command-prefix';
 import { sandboxMkDir } from '@agentuity/server';
 
@@ -14,7 +14,7 @@ export const mkdirSubcommand = createCommand({
 	name: 'mkdir',
 	description: 'Create a directory in a sandbox',
 	tags: ['slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('cloud sandbox mkdir sbx_abc123 /path/to/dir'),
@@ -44,7 +44,8 @@ export const mkdirSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, opts, options, auth, region, logger, orgId } = ctx;
+		const { args, opts, options, auth, logger, orgId, config } = ctx;
+		const region = await getSandboxRegion(logger, auth, config?.name, args.sandboxId, orgId);
 		const client = createSandboxClient(logger, auth, region);
 
 		await sandboxMkDir(client, {

package/src/cmd/cloud/sandbox/rm.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
-import { createSandboxClient } from './util';
+import { getSandboxRegion, createSandboxClient } from './util';
 import { getCommand } from '../../../command-prefix';
 import { sandboxRmFile } from '@agentuity/server';
 
@@ -14,7 +14,7 @@ export const rmSubcommand = createCommand({
 	name: 'rm',
 	description: 'Remove a file from a sandbox',
 	tags: ['slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('cloud sandbox rm sbx_abc123 /path/to/file.txt'),
@@ -31,7 +31,8 @@ export const rmSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, options, auth, region, logger, orgId } = ctx;
+		const { args, options, auth, logger, orgId, config } = ctx;
+		const region = await getSandboxRegion(logger, auth, config?.name, args.sandboxId, orgId);
 		const client = createSandboxClient(logger, auth, region);
 
 		await sandboxRmFile(client, {

package/src/cmd/cloud/sandbox/rmdir.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
-import { createSandboxClient } from './util';
+import { createSandboxClient, getSandboxRegion } from './util';
 import { getCommand } from '../../../command-prefix';
 import { sandboxRmDir } from '@agentuity/server';
 
@@ -14,7 +14,7 @@ export const rmdirSubcommand = createCommand({
 	name: 'rmdir',
 	description: 'Remove a directory from a sandbox',
 	tags: ['slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('cloud sandbox rmdir sbx_abc123 /path/to/dir'),
@@ -44,7 +44,8 @@ export const rmdirSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, opts, options, auth, region, logger, orgId } = ctx;
+		const { args, opts, options, auth, logger, orgId, config } = ctx;
+		const region = await getSandboxRegion(logger, auth, config?.name, args.sandboxId, orgId);
 		const client = createSandboxClient(logger, auth, region);
 
 		await sandboxRmDir(client, {

package/src/cmd/cloud/sandbox/run.ts

@@ -2,9 +2,11 @@ import { z } from 'zod';
 import { Writable } from 'node:stream';
 import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
-import { createSandboxClient, parseFileArgs } from './util';
+import { createSandboxClient, parseFileArgs, cacheSandboxRegion } from './util';
 import { getCommand } from '../../../command-prefix';
 import { sandboxRun } from '@agentuity/server';
+import { validateAptDependencies } from '../../../utils/apt-validator';
+import { ErrorCode } from '../../../errors';
 
 const SandboxRunResponseSchema = z.object({
 	sandboxId: z.string().describe('Sandbox ID'),
@@ -37,10 +39,7 @@ export const runSubcommand = createCommand({
 			command: z.array(z.string()).describe('Command and arguments to execute'),
 		}),
 		options: z.object({
-			runtime: z
-				.string()
-				.optional()
-				.describe('Runtime name (e.g., "bun:1", "python:3.14")'),
+			runtime: z.string().optional().describe('Runtime name (e.g., "bun:1", "python:3.14")'),
 			runtimeId: z.string().optional().describe('Runtime ID (e.g., "srt_xxx")'),
 			name: z.string().optional().describe('Sandbox name'),
 			description: z.string().optional().describe('Sandbox description'),
@@ -69,10 +68,53 @@ export const runSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, opts, options, auth, region, logger, orgId } = ctx;
+		const { args, opts, options, auth, region, config, logger, orgId } = ctx;
 		const client = createSandboxClient(logger, auth, region);
 		const started = Date.now();
 
+		// Validate apt dependencies before running sandbox
+		if (opts.dependency && opts.dependency.length > 0) {
+			const aptValidation = await tui.spinner({
+				message: 'Validating apt dependencies...',
+				type: 'simple',
+				callback: async () => {
+					return await validateAptDependencies(opts.dependency!, region, config, logger);
+				},
+			});
+
+			if (aptValidation.invalid.length > 0) {
+				if (options.json) {
+					return {
+						sandboxId: '',
+						exitCode: 1,
+						durationMs: 0,
+						errors: aptValidation.invalid.map((pkg) => ({
+							type: 'invalid-apt-dependency',
+							package: pkg.package,
+							error: pkg.error,
+							searchUrl: pkg.searchUrl,
+							availableVersions: pkg.availableVersions,
+						})),
+					} as never;
+				}
+
+				tui.error('Invalid apt dependencies:');
+				tui.newline();
+				for (const pkg of aptValidation.invalid) {
+					tui.bullet(`${tui.bold(pkg.package)}: ${pkg.error}`);
+					if (pkg.availableVersions && pkg.availableVersions.length > 0) {
+						tui.muted(`    Available versions: ${pkg.availableVersions.join(', ')}`);
+					}
+					tui.muted(`    Search: ${tui.link(pkg.searchUrl)}`);
+				}
+				tui.newline();
+				tui.fatal(
+					'Fix the apt dependencies and try again. Search for valid packages at: https://packages.debian.org/stable/',
+					ErrorCode.CONFIG_INVALID
+				);
+			}
+		}
+
 		const envMap: Record<string, string> = {};
 		if (opts.env) {
 			for (const e of opts.env) {
@@ -142,6 +184,9 @@ export const runSubcommand = createCommand({
 				logger,
 			});
 
+			// Cache the region for future lookups (sandbox is destroyed after run but cache helps with lookups during execution)
+			await cacheSandboxRegion(config?.name, result.sandboxId, region);
+
 			const duration = Date.now() - started;
 			const output = outputChunks.join('');
 

package/src/cmd/cloud/sandbox/runtime/index.ts

@@ -14,7 +14,7 @@ export const runtimeCommand = createCommand({
 		},
 	],
 	subcommands: [listSubcommand],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 });
 
 export default runtimeCommand;

package/src/cmd/cloud/sandbox/runtime/list.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import { createCommand } from '../../../../types';
 import * as tui from '../../../../tui';
-import { createSandboxClient } from '../util';
 import { getCommand } from '../../../../command-prefix';
 import { runtimeList } from '@agentuity/server';
+import { getGlobalCatalystAPIClient } from '../../../../config';
 
 const RuntimeInfoSchema = z.object({
 	id: z.string().describe('Runtime ID'),
@@ -21,7 +21,7 @@ export const listSubcommand = createCommand({
 	aliases: ['ls'],
 	description: 'List available sandbox runtimes',
 	tags: ['read-only', 'slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	idempotent: true,
 	examples: [
 		{
@@ -38,8 +38,8 @@ export const listSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { opts, options, auth, region, logger, orgId } = ctx;
-		const client = createSandboxClient(logger, auth, region);
+		const { opts, options, auth, logger, orgId, config } = ctx;
+		const client = await getGlobalCatalystAPIClient(logger, auth, config?.name);
 
 		const result = await runtimeList(client, {
 			orgId,

package/src/cmd/cloud/sandbox/snapshot/create.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { createCommand } from '../../../../types';
 import * as tui from '../../../../tui';
-import { createSandboxClient } from '../util';
+import { getSandboxRegion, createSandboxClient } from '../util';
 import { getCommand } from '../../../../command-prefix';
 import { snapshotCreate } from '@agentuity/server';
 
@@ -23,7 +23,7 @@ export const createSubcommand = createCommand({
 	name: 'create',
 	description: 'Create a snapshot from a sandbox',
 	tags: ['slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('cloud sandbox snapshot create sbx_abc123'),
@@ -34,7 +34,9 @@ export const createSubcommand = createCommand({
 			description: 'Create a tagged snapshot',
 		},
 		{
-			command: getCommand('cloud sandbox snapshot create sbx_abc123 --name "My Snapshot" --description "Initial setup"'),
+			command: getCommand(
+				'cloud sandbox snapshot create sbx_abc123 --name "My Snapshot" --description "Initial setup"'
+			),
 			description: 'Create a named snapshot with description',
 		},
 	],
@@ -54,7 +56,7 @@ export const createSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, opts, options, auth, region, logger, orgId } = ctx;
+		const { args, opts, options, auth, logger, orgId, config } = ctx;
 
 		if (opts.name && !SNAPSHOT_NAME_REGEX.test(opts.name)) {
 			logger.fatal(
@@ -64,7 +66,9 @@ export const createSubcommand = createCommand({
 
 		if (opts.tag) {
 			if (opts.tag.length > MAX_SNAPSHOT_TAG_LENGTH) {
-				logger.fatal(`Invalid snapshot tag: must be at most ${MAX_SNAPSHOT_TAG_LENGTH} characters`);
+				logger.fatal(
+					`Invalid snapshot tag: must be at most ${MAX_SNAPSHOT_TAG_LENGTH} characters`
+				);
 			}
 			if (!SNAPSHOT_TAG_REGEX.test(opts.tag)) {
 				logger.fatal(
@@ -73,6 +77,8 @@ export const createSubcommand = createCommand({
 			}
 		}
 
+		const profileName = config?.name;
+		const region = await getSandboxRegion(logger, auth, profileName, args.sandboxId, orgId);
 		const client = createSandboxClient(logger, auth, region);
 
 		const snapshot = await snapshotCreate(client, {

package/src/cmd/cloud/sandbox/snapshot/delete.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import { createCommand } from '../../../../types';
 import * as tui from '../../../../tui';
-import { createSandboxClient } from '../util';
 import { getCommand } from '../../../../command-prefix';
 import { snapshotDelete } from '@agentuity/server';
+import { getGlobalCatalystAPIClient } from '../../../../config';
 
 const SnapshotDeleteResponseSchema = z.object({
 	success: z.boolean().describe('Whether the operation succeeded'),
@@ -16,7 +16,7 @@ export const deleteSubcommand = createCommand({
 	aliases: ['del', 'rm', 'remove'],
 	description: 'Delete a snapshot',
 	tags: ['destructive', 'deletes-resource', 'slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	idempotent: true,
 	examples: [
 		{
@@ -39,7 +39,7 @@ export const deleteSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, options, opts, auth, region, logger, orgId } = ctx;
+		const { args, options, opts, auth, logger, orgId, config } = ctx;
 
 		if (!opts.confirm) {
 			const confirmed = await tui.confirm(`Delete snapshot "${args.snapshotId}"?`, false);
@@ -53,7 +53,7 @@ export const deleteSubcommand = createCommand({
 			}
 		}
 
-		const client = createSandboxClient(logger, auth, region);
+		const client = await getGlobalCatalystAPIClient(logger, auth, config?.name);
 
 		await snapshotDelete(client, {
 			snapshotId: args.snapshotId,

package/src/cmd/cloud/sandbox/snapshot/get.ts

@@ -1,11 +1,11 @@
 import { z } from 'zod';
 import { createCommand } from '../../../../types';
 import * as tui from '../../../../tui';
-import { createSandboxClient } from '../util';
 import { getCommand } from '../../../../command-prefix';
 import { snapshotGet, sandboxList } from '@agentuity/server';
 import type { SnapshotFileInfo } from '@agentuity/server';
 import type { SandboxInfo } from '@agentuity/core';
+import { getGlobalCatalystAPIClient } from '../../../../config';
 
 const SnapshotFileSchema = z.object({
 	path: z.string(),
@@ -39,7 +39,7 @@ export const getSubcommand = createCommand({
 	aliases: ['info', 'show'],
 	description: 'Get snapshot details',
 	tags: ['slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('cloud sandbox snapshot get snp_abc123'),
@@ -54,8 +54,8 @@ export const getSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, options, auth, region, logger, orgId } = ctx;
-		const client = createSandboxClient(logger, auth, region);
+		const { args, options, auth, logger, orgId, config } = ctx;
+		const client = await getGlobalCatalystAPIClient(logger, auth, config?.name);
 
 		const snapshot = await snapshotGet(client, {
 			snapshotId: args.snapshotId,

package/src/cmd/cloud/sandbox/snapshot/index.ts

@@ -22,7 +22,7 @@ export const snapshotCommand = createCommand({
 		},
 	],
 	subcommands: [createSubcommand, listSubcommand, getSubcommand, deleteSubcommand, tagSubcommand],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 });
 
 export default snapshotCommand;

package/src/cmd/cloud/sandbox/snapshot/list.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import { createCommand } from '../../../../types';
 import * as tui from '../../../../tui';
-import { createSandboxClient } from '../util';
 import { getCommand } from '../../../../command-prefix';
 import { snapshotList } from '@agentuity/server';
+import { getGlobalCatalystAPIClient } from '../../../../config';
 
 const SnapshotInfoSchema = z.object({
 	snapshotId: z.string(),
@@ -26,7 +26,7 @@ export const listSubcommand = createCommand({
 	aliases: ['ls'],
 	description: 'List snapshots',
 	tags: ['slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('cloud sandbox snapshot list'),
@@ -47,8 +47,8 @@ export const listSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { opts, options, auth, region, logger, orgId } = ctx;
-		const client = createSandboxClient(logger, auth, region);
+		const { opts, options, auth, logger, orgId, config } = ctx;
+		const client = await getGlobalCatalystAPIClient(logger, auth, config?.name);
 
 		const result = await snapshotList(client, {
 			sandboxId: opts.sandbox,

package/src/cmd/cloud/sandbox/snapshot/tag.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import { createCommand } from '../../../../types';
 import * as tui from '../../../../tui';
-import { createSandboxClient } from '../util';
 import { getCommand } from '../../../../command-prefix';
 import { snapshotTag } from '@agentuity/server';
+import { getGlobalCatalystAPIClient } from '../../../../config';
 
 const SNAPSHOT_TAG_REGEX = /^[a-zA-Z0-9_][a-zA-Z0-9._-]*$/;
 const MAX_SNAPSHOT_TAG_LENGTH = 128;
@@ -17,7 +17,7 @@ export const tagSubcommand = createCommand({
 	name: 'tag',
 	description: 'Add or update a tag on a snapshot',
 	tags: ['slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('cloud sandbox snapshot tag snp_abc123 latest'),
@@ -40,8 +40,8 @@ export const tagSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, opts, options, auth, region, logger, orgId } = ctx;
-		const client = createSandboxClient(logger, auth, region);
+		const { args, opts, options, auth, logger, orgId, config } = ctx;
+		const client = await getGlobalCatalystAPIClient(logger, auth, config?.name);
 
 		if (!args.tag && !opts.clear) {
 			throw new Error('Either provide a tag name or use --clear to remove the tag');
@@ -49,7 +49,9 @@ export const tagSubcommand = createCommand({
 
 		if (args.tag) {
 			if (args.tag.length > MAX_SNAPSHOT_TAG_LENGTH) {
-				logger.fatal(`Invalid snapshot tag: must be at most ${MAX_SNAPSHOT_TAG_LENGTH} characters`);
+				logger.fatal(
+					`Invalid snapshot tag: must be at most ${MAX_SNAPSHOT_TAG_LENGTH} characters`
+				);
 			}
 			if (!SNAPSHOT_TAG_REGEX.test(args.tag)) {
 				logger.fatal(

package/src/cmd/cloud/sandbox/upload.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { readFileSync, statSync } from 'node:fs';
 import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
-import { createSandboxClient } from './util';
+import { createSandboxClient, getSandboxRegion } from './util';
 import { getCommand } from '../../../command-prefix';
 import { sandboxUploadArchive } from '@agentuity/server';
 
@@ -11,7 +11,7 @@ export const uploadSubcommand = createCommand({
 	aliases: ['ul'],
 	description: 'Upload a compressed archive to a sandbox and extract it',
 	tags: ['slow', 'requires-auth'],
-	requires: { auth: true, region: true, org: true },
+	requires: { auth: true, org: true },
 	examples: [
 		{
 			command: getCommand('cloud sandbox upload sbx_abc123 ./archive.tar.gz'),
@@ -45,8 +45,9 @@ export const uploadSubcommand = createCommand({
 	},
 
 	async handler(ctx) {
-		const { args, opts, options, auth, region, logger, orgId } = ctx;
+		const { args, opts, options, auth, logger, orgId, config } = ctx;
 
+		const region = await getSandboxRegion(logger, auth, config?.name, args.sandboxId, orgId);
 		const client = createSandboxClient(logger, auth, region);
 
 		const stat = statSync(args.archive);

package/src/cmd/cloud/sandbox/util.ts

@@ -1,14 +1,73 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import type { Logger, FileToWrite } from '@agentuity/core';
-import { APIClient, getServiceUrls } from '@agentuity/server';
+import { APIClient, getServiceUrls, sandboxGet } from '@agentuity/server';
 import type { AuthData } from '../../../types';
+import { getGlobalCatalystAPIClient } from '../../../config';
+import { getResourceRegion, setResourceRegion, deleteResourceRegion } from '../../../cache';
+import * as tui from '../../../tui';
+import { ErrorCode } from '../../../errors';
 
 export function createSandboxClient(logger: Logger, auth: AuthData, region: string): APIClient {
 	const urls = getServiceUrls(region);
 	return new APIClient(urls.catalyst, logger, auth.apiKey);
 }
 
+/**
+ * Look up the region for a sandbox, using cache-first strategy.
+ * Falls back to API lookup if not in cache.
+ */
+export async function getSandboxRegion(
+	logger: Logger,
+	auth: AuthData,
+	profileName = 'production',
+	sandboxId: string,
+	orgId: string
+): Promise<string> {
+	// Check cache first
+	const cachedRegion = await getResourceRegion('sandbox', profileName, sandboxId);
+	if (cachedRegion) {
+		logger.trace(`[sandbox] Found cached region for ${sandboxId}: ${cachedRegion}`);
+		return cachedRegion;
+	}
+
+	// Fallback to API lookup using global client
+	logger.trace(`[sandbox] Cache miss for ${sandboxId}, fetching from API`);
+	const globalClient = await getGlobalCatalystAPIClient(logger, auth, profileName);
+
+	const sandbox = await sandboxGet(globalClient, { sandboxId, orgId });
+	if (!sandbox.region) {
+		tui.fatal(`Sandbox '${sandboxId}' has no region information`, ErrorCode.RESOURCE_NOT_FOUND);
+	}
+
+	// Cache the result
+	await setResourceRegion('sandbox', profileName, sandboxId, sandbox.region);
+	logger.trace(`[sandbox] Cached region for ${sandboxId}: ${sandbox.region}`);
+
+	return sandbox.region;
+}
+
+/**
+ * Cache the region for a sandbox after create/run operations
+ */
+export async function cacheSandboxRegion(
+	profileName = 'production',
+	sandboxId: string,
+	region: string
+): Promise<void> {
+	await setResourceRegion('sandbox', profileName, sandboxId, region);
+}
+
+/**
+ * Clear cached region for a sandbox after delete
+ */
+export async function clearSandboxRegionCache(
+	profileName = 'production',
+	sandboxId: string
+): Promise<void> {
+	await deleteResourceRegion('sandbox', profileName, sandboxId);
+}
+
 /**
  * Parse --file arguments and read file contents.
  *