Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

fix(sandbox): report a missing Daytona snapshot permission as 403, not an invalid key (#477)

Ethan Stoner58940a721147
diff --git a/.changeset/daytona-permission-vs-invalid-key.md b/.changeset/daytona-permission-vs-invalid-key.md
new file mode 100644
index 000000000..e12c64177
--- /dev/null
+++ b/.changeset/daytona-permission-vs-invalid-key.md
@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge": patch
+---
+
+Report a Daytona key that cannot register snapshots as missing key permissions (403) instead of an invalid API key (422), and name the grants to add in the Daytona dashboard.
diff --git a/packages/trueforge/src/apis/sandboxProviders.ts b/packages/trueforge/src/apis/sandboxProviders.ts
index 9df3afa23..a4a77aad7 100644
--- a/packages/trueforge/src/apis/sandboxProviders.ts
+++ b/packages/trueforge/src/apis/sandboxProviders.ts
@@ -7,6 +7,7 @@ import { getSandboxProviderRoute, putSandboxProviderRoute } from '../routes/sand
import {
checkSnapshotStatus,
isDaytonaAuthError,
+ isDaytonaPermissionError,
toDaytonaSandboxProvider,
toSandboxStatus,
} from '../sandbox/providerUtils';
@@ -106,6 +107,17 @@ export function createSandboxProvidersRouter<TTransaction>(deps: SandboxProvider
if (isDaytonaAuthError(error)) {
return c.json({ error: { message: 'Daytona rejected the API key — check the credentials' } }, 422);
}
+ if (isDaytonaPermissionError(error)) {
+ return c.json(
+ {
+ error: {
+ message:
+ 'Daytona denied access: the API key is missing required permissions. Grant write:sandboxes, write:snapshots, and delete:snapshots on the key in the Daytona dashboard, then try again.',
+ },
+ },
+ 422,
+ );
+ }
throw error;
}
};
diff --git a/packages/trueforge/src/sandbox/providerUtils.ts b/packages/trueforge/src/sandbox/providerUtils.ts
index 65974eb36..0d815dc36 100644
--- a/packages/trueforge/src/sandbox/providerUtils.ts
+++ b/packages/trueforge/src/sandbox/providerUtils.ts
@@ -16,9 +16,13 @@ import {
type SandboxStatus,
} from '../schemas/sandboxProvider';
-/** Daytona rejected the credentials (401 unauthorized / 403 forbidden); retrying the same key cannot succeed. */
+/** Daytona rejected the credentials (401 unauthorized); retrying the same key cannot succeed. */
export function isDaytonaAuthError(error: unknown): boolean {
- return error instanceof DaytonaError && (error.statusCode === 401 || error.statusCode === 403);
+ return error instanceof DaytonaError && error.statusCode === 401;
+}
+
+export function isDaytonaPermissionError(error: unknown): boolean {
+ return error instanceof DaytonaError && error.statusCode === 403;
}
/**
diff --git a/packages/trueforge/tests/unit/apis/sandboxProviders.test.ts b/packages/trueforge/tests/unit/apis/sandboxProviders.test.ts
index fa2220862..8f86cd883 100644
--- a/packages/trueforge/tests/unit/apis/sandboxProviders.test.ts
+++ b/packages/trueforge/tests/unit/apis/sandboxProviders.test.ts
@@ -1,6 +1,7 @@
// Stub the Daytona-touching helpers so the router never talks to Daytona: the PUT path builds via
-// toDaytonaSandboxProvider, and the GET path refreshes via checkSnapshotStatus. isDaytonaAuthError
-// and toSandboxStatus stay real so the auth-error mapping and PUT wire shape are exercised.
+// toDaytonaSandboxProvider, and the GET path refreshes via checkSnapshotStatus. isDaytonaAuthError,
+// isDaytonaPermissionError and toSandboxStatus stay real so the error mapping and PUT wire shape are
+// exercised.
jest.mock('../../../src/sandbox/providerUtils', () => {
const actual = jest.requireActual('../../../src/sandbox/providerUtils');
return { ...actual, toDaytonaSandboxProvider: jest.fn(), checkSnapshotStatus: jest.fn() };
@@ -165,6 +166,20 @@ describe('sandboxProviders router', () => {
expect(response.status).toBe(422);
});
+ it('PUT returns 422 naming the permissions when the key cannot register snapshots', async () => {
+ mockProviderFactory.mockReturnValue(
+ stubProvider({ buildImage: jest.fn().mockRejectedValue(new DaytonaError('Access denied', 403)) }),
+ );
+ const response = await settingsRouter.request('/', putInit(putBody));
+ expect(response.status).toBe(422);
+ expect(await response.json()).toEqual({
+ error: {
+ message:
+ 'Daytona denied access: the API key is missing required permissions. Grant write:sandboxes, write:snapshots, and delete:snapshots on the key in the Daytona dashboard, then try again.',
+ },
+ });
+ });
+
it('PUT does not persist config when the build call fails auth', async () => {
const { settingsRouter: router } = await createRouters();
mockProviderFactory.mockReturnValue(