@finalai/daytona-agent-provider 0.9.0 → 0.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/HOSTING.md +334 -245
- package/README.md +84 -26
- package/dist/modules/sandboxes/daytona.d.mts +18 -20
- package/dist/modules/sandboxes/daytona.mjs +234 -539
- package/dist/modules/sandboxes/daytona.mjs.map +3 -3
- package/dist/modules/sandboxes/environment.d.mts +5 -36
- package/dist/modules/sandboxes/environment.mjs +11 -59
- package/dist/modules/sandboxes/environment.mjs.map +3 -3
- package/dist/modules/sandboxes/index.d.mts +9 -60
- package/dist/modules/sandboxes/index.mjs +14 -41
- package/dist/modules/sandboxes/index.mjs.map +3 -3
- package/dist/modules/sandboxes/session.d.mts +2 -3
- package/dist/modules/sandboxes/session.mjs +8 -51
- package/dist/modules/sandboxes/session.mjs.map +2 -2
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -1,23 +1,81 @@
|
|
|
1
1
|
# @finalai/daytona-agent-provider
|
|
2
2
|
|
|
3
|
+
The `daytona` sandbox provider: sandboxes in your own Daytona account, driven through
|
|
4
|
+
Daytona's public API and implementing only the `@finalai/agent-provider` sandbox
|
|
5
|
+
contract. `/sandboxes` exports `daytona(...)`, the provider environment a caller creates
|
|
6
|
+
sandboxes from; `/sandboxes/daytona` exports the provider a host runs.
|
|
7
|
+
|
|
8
|
+
```ts
|
|
9
|
+
import { defineSandboxSetup } from '@finalai/agents/sandboxes';
|
|
10
|
+
import { daytona } from '@finalai/daytona-agent-provider/sandboxes';
|
|
11
|
+
|
|
12
|
+
const box = await project.sandboxes.create(
|
|
13
|
+
daytona({
|
|
14
|
+
credential: { secretRef: 'DAYTONA_API_KEY' },
|
|
15
|
+
image: 'node:26',
|
|
16
|
+
resources: { cpu: 2, memory: 4 },
|
|
17
|
+
region: 'eu',
|
|
18
|
+
autoStopMinutes: 30,
|
|
19
|
+
}),
|
|
20
|
+
{
|
|
21
|
+
setup: defineSandboxSetup({
|
|
22
|
+
repositories: [{ alias: 'app', repository: 'acme/app' }],
|
|
23
|
+
steps: [{ cwd: 'app', run: 'pnpm install' }],
|
|
24
|
+
network: { allow: ['registry.npmjs.org'] },
|
|
25
|
+
}),
|
|
26
|
+
},
|
|
27
|
+
);
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Provider environment
|
|
31
|
+
|
|
32
|
+
`daytona({...})` holds Daytona's own options only:
|
|
33
|
+
|
|
34
|
+
- `credential`: the Daytona API key by reference, the name of a project secret. It is
|
|
35
|
+
read through the host's `credentials.secret`; a missing reference or value fails with
|
|
36
|
+
`credential_missing` when the sandbox is created.
|
|
37
|
+
- `image` (built into a Daytona snapshot once, by `prepare`) or `snapshot` (an existing
|
|
38
|
+
one by name), and `resources` for a snapshot built from an image.
|
|
39
|
+
- `region`, `user`, `workingDirectory`, `labels`.
|
|
40
|
+
- `autoStopMinutes` (Daytona stops an idle sandbox; default 15) and `autoArchiveMinutes`.
|
|
41
|
+
- `park`: what parking does, `stop` (default) or `archive`. Both keep the disk.
|
|
42
|
+
|
|
43
|
+
What should be on the machine (repositories, variables, setup steps, services, named
|
|
44
|
+
commands, network policy, notes) is a provider-neutral sandbox setup. The platform
|
|
45
|
+
applies it through the sandbox handle after each attach; the provider never runs it.
|
|
46
|
+
|
|
47
|
+
## Lifecycle
|
|
48
|
+
|
|
49
|
+
- `create` validates the options, the credential and the setup's network policy, and
|
|
50
|
+
records the sandbox's Daytona name. Nothing exists in Daytona yet.
|
|
51
|
+
- The first `attach` creates the Daytona sandbox with the setup's network policy in its
|
|
52
|
+
create body, so the policy is enforced from the first boot. Daytona has no deny list
|
|
53
|
+
and cannot mix domains and IPv4 CIDRs in one allow list; a setup asking for either is
|
|
54
|
+
refused at `create`.
|
|
55
|
+
- `attach` reports `fresh` when the disk is new (first attach, or a sandbox Daytona lost
|
|
56
|
+
and the provider created again under its name) and `booted` when the sandbox was
|
|
57
|
+
stopped, archived or still booting. A sandbox in Daytona's error state is kept for
|
|
58
|
+
recovery and the attach fails.
|
|
59
|
+
- `detach` leaves the sandbox to Daytona's auto-stop. `park` stops or archives it.
|
|
60
|
+
`delete` deletes it; deleting one already gone succeeds.
|
|
61
|
+
|
|
62
|
+
Its sandboxes offer `files` with write access and `shell` with execute access. The
|
|
63
|
+
platform gates each handle call by the grant a session holds.
|
|
64
|
+
|
|
65
|
+
## Networking
|
|
66
|
+
|
|
3
67
|
Compose networking through the generic `networking: SandboxNetworkingExtensionIface`
|
|
4
|
-
configuration. The provider supplies Daytona lifecycle
|
|
5
|
-
extension owns routing, readiness, policy persistence and lease cleanup
|
|
6
|
-
|
|
7
|
-
`@finalai/final-agent-provider/sandboxes/egress`; this package has no dependency on
|
|
8
|
-
that implementation. `workspaceNetworkingBootFence` controls the provider's
|
|
68
|
+
configuration. The provider supplies Daytona lifecycle and firewall operations; the
|
|
69
|
+
extension owns routing, readiness, policy persistence and lease cleanup, keyed by the
|
|
70
|
+
platform's sandbox id. `workspaceNetworkingBootFence` controls the provider's
|
|
9
71
|
startup-window guarantee, independently of the extension's tunnel technology.
|
|
10
72
|
A stopped sandbox's control-plane policy readback does not prove pre-boot enforcement.
|
|
11
|
-
By default
|
|
12
|
-
Setting the option to true refuses an unverified stopped
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
by the host; no Final platform credential is required. Declare the Daytona API key by
|
|
18
|
-
reference, `daytona({ credential: { secretRef: 'DAYTONA_API_KEY' } })`; it is read
|
|
19
|
-
through the context's `credentials.secret`, and a missing reference or value fails
|
|
20
|
-
with `credential_missing`.
|
|
73
|
+
By default an attach that wakes a sandbox logs this window, then fences the running
|
|
74
|
+
sandbox before tools. Setting the option to true refuses an unverified stopped wake.
|
|
75
|
+
Setting it to false skips only the pre-boot fence; runtime fences requested by the
|
|
76
|
+
networking extension and teardown fences are still attempted. An account that rejects
|
|
77
|
+
network settings cannot provide those outer fences; the namespace guard and explicit
|
|
78
|
+
warning-backed startup window remain the supported fallback.
|
|
21
79
|
|
|
22
80
|
Managed policy capture requires a complete policy readback; omitted allowlist fields are not treated as confirmed unrestricted access. Updates explicitly replace block-all and both allowlist fields, following [Daytona’s network-control contract](https://www.daytona.io/docs/en/network-limits/). Failed managed policy confirmation re-applies the provider fence where supported.
|
|
23
81
|
|
|
@@ -25,18 +83,18 @@ Allowlist updates explicitly clear the other stored list using Daytona's require
|
|
|
25
83
|
|
|
26
84
|
Domain-list updates explicitly set `networkBlockAll: false` in the same request for compatibility with the last public Daytona server, where domain-only updates preserve block-all. CIDR updates already imply false. See [the public server implementation](https://github.com/daytonaio/daytona/blob/v0.190.0/apps/api/src/sandbox/services/sandbox.service.ts#L3067). No intermediate allow-all request is issued.
|
|
27
85
|
|
|
28
|
-
Legacy sandboxes with both CIDR and domain lists must be repaired through the provider API before managed opt-in. The adapter refuses mixed policy snapshots rather than silently changing their meaning. Retain the networking extension while any
|
|
86
|
+
Legacy sandboxes with both CIDR and domain lists must be repaired through the provider API before managed opt-in. The adapter refuses mixed policy snapshots rather than silently changing their meaning. Retain the networking extension while any managed sandbox still exists; removing it refuses attach until the original policy is explicitly restored.
|
|
29
87
|
|
|
30
88
|
## Durable processes
|
|
31
89
|
|
|
32
90
|
The `daytona` sandbox offers durable processes (`SandboxCapability.DurableProcesses`:
|
|
33
|
-
`spawn({ durable: true })` and `attachProcess`)
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
91
|
+
`spawn({ durable: true })` and `attachProcess`). Each runs in a Daytona process session
|
|
92
|
+
of its own, which a dropped handle leaves running. Its `timeoutMs` is enforced inside the
|
|
93
|
+
sandbox by coreutils `timeout` (exit 124, or a SIGKILL 5 s later for a process that
|
|
94
|
+
ignores SIGTERM), so the image needs `timeout` as well as bash. Attaching replays the
|
|
95
|
+
session's log from the start and skips the bytes the caller already has, so output is
|
|
96
|
+
retained in full while the session exists, and an attached stream starts exactly where
|
|
97
|
+
asked. Killing a durable process deletes its session. Exited durable sessions are kept
|
|
98
|
+
for attaching; each durable spawn deletes the oldest exited ones beyond 64. A ref from
|
|
99
|
+
another sandbox, or of a deleted session (killed, collected, or lost with the sandbox),
|
|
100
|
+
attaches to nothing.
|
|
@@ -1,17 +1,13 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { type
|
|
1
|
+
import type { JsonValue } from '@finalai/agent-provider';
|
|
2
|
+
import { NetworkPolicy, type NetworkPolicyIface, type SandboxNetworkingExtensionIface, type SandboxProviderIface, type SandboxSetupIface } from '@finalai/agent-provider/sandbox';
|
|
3
3
|
import * as z from 'zod';
|
|
4
4
|
import { type DaytonaClientIface, type DaytonaFetchIface, type DaytonaWebSocketFactoryIface } from "../client/index.mjs";
|
|
5
|
-
import { DaytonaSessionEndPolicy } from "./environment.mjs";
|
|
6
5
|
import { type DaytonaSandboxSessionIface } from "./session.mjs";
|
|
7
|
-
export { DAYTONA_SANDBOX_SPECIFIER,
|
|
6
|
+
export { DAYTONA_SANDBOX_SPECIFIER, DaytonaParkPolicy } from "./environment.mjs";
|
|
8
7
|
export type { DaytonaSandboxSessionIface } from "./session.mjs";
|
|
9
|
-
export declare const
|
|
8
|
+
export declare const daytonaSandboxName: (args: {
|
|
10
9
|
organizationId: string;
|
|
11
|
-
|
|
12
|
-
conversationId: string | null;
|
|
13
|
-
target: string;
|
|
14
|
-
conversationWorkspace: boolean;
|
|
10
|
+
sandboxId: string;
|
|
15
11
|
}) => Promise<string>;
|
|
16
12
|
export interface DaytonaSandboxProviderConfigIface {
|
|
17
13
|
networking?: SandboxNetworkingExtensionIface;
|
|
@@ -53,17 +49,19 @@ declare const artifactSchema: z.ZodObject<{
|
|
|
53
49
|
}, z.core.$strip>;
|
|
54
50
|
export type DaytonaSandboxArtifact = z.infer<typeof artifactSchema>;
|
|
55
51
|
declare const stateSchema: z.ZodObject<{
|
|
56
|
-
version: z.ZodLiteral<
|
|
57
|
-
sandboxId: z.ZodString;
|
|
52
|
+
version: z.ZodLiteral<2>;
|
|
58
53
|
sandboxName: z.ZodString;
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
54
|
+
sandboxId: z.ZodNullable<z.ZodString>;
|
|
55
|
+
workingDirectory: z.ZodNullable<z.ZodString>;
|
|
56
|
+
network: z.ZodNullable<z.ZodObject<{
|
|
57
|
+
mode: z.ZodEnum<typeof NetworkPolicy>;
|
|
58
|
+
allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
59
|
+
}, z.core.$strip>>;
|
|
60
|
+
ports: z.ZodArray<z.ZodNumber>;
|
|
61
|
+
seedPending: z.ZodBoolean;
|
|
62
|
+
networkingManaged: z.ZodBoolean;
|
|
66
63
|
}, z.core.$strip>;
|
|
67
|
-
export type
|
|
68
|
-
export type DaytonaSandboxProviderIface = SandboxProviderIface<JsonValue,
|
|
64
|
+
export type DaytonaSandboxResourceState = z.infer<typeof stateSchema>;
|
|
65
|
+
export type DaytonaSandboxProviderIface = SandboxProviderIface<JsonValue, DaytonaSandboxArtifact, DaytonaSandboxResourceState, DaytonaSandboxSessionIface>;
|
|
66
|
+
export declare const daytonaNetworkPolicyOf: (setup: SandboxSetupIface | null) => NetworkPolicyIface | null;
|
|
69
67
|
export declare const createDaytonaSandboxProvider: (config: DaytonaSandboxProviderConfigIface) => DaytonaSandboxProviderIface;
|