TaskAgent
API reference for Task Agents (clrk.apoxy.dev/v1alpha1)
API Group: clrk.apoxy.dev/v1alpha1
Operations
List TaskAgent
GET/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/taskagents
List TaskAgent
Response
200: OK
List TaskAgent
GET/apis/clrk.apoxy.dev/v1alpha1/taskagents
List TaskAgent
Response
200: OK
Create TaskAgent
POST/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/taskagents
Create a TaskAgent
Request Body
Spec fields (TaskAgentSpec):
| Field | Type | Description |
|---|---|---|
delivery | AgentDelivery | Delivery selects how the request payload reaches the agent. Stdin (default) writes a CloudEvents structured-mode JSON envelope to the agent's stdin. Metadata closes stdin and exposes an IMDS-style HTTP server inside the sandbox; the agent fetches via $CLRK_METADATA_URL. |
egressRefs | AgentEgressRef[] | EgressRefs references EgressGateway objects for outbound access. Token budgets are configured on AIProviderRoute, not here. |
identity | AgentIdentity | Identity configures user identity extraction from incoming requests. |
maxConcurrent | integer (int32) | MaxConcurrent caps how many executions of this agent can run simultaneously across all workers. 0 = unlimited. |
resources | ExecutionResources | Resources defines per-execution CPU/memory limits. |
schedule | string | Schedule adds a cron trigger. Does NOT disable HTTP triggering. |
scheduleInput | RawExtension | ScheduleInput is the JSON body sent to the agent on cron triggers. |
state | AgentState | State configures persistent state across executions. |
streaming | AgentStreaming | Streaming configures stdout/stderr streaming behavior. |
template | AgentSandboxRevisionTemplate | Template defines the sandbox revision template. Changes to this field trigger creation of a new AgentSandboxRevision. (required) |
timeout | Duration | Timeout caps how long a single execution can run. Accepts a Go duration string ("100s", "5m", "1h30m"). Defaults to 100s. |
warmPoolIdleTTL | Duration | WarmPoolIdleTTL bounds how long a pre-warmed sandbox can sit in the pool before it is evicted and replaced. Defaults to 10 minutes when unset. Bounds resource-leak accumulation in long-idle agent processes (file descriptors, anon memory, language-runtime caches) at the cost of a cold-fill every IdleTTL when traffic is sparse. |
warmPoolSize | integer (int32) | WarmPoolSize is the per-worker target for pre-Created sandboxes kept Ready (rootfs mounted, TAP+netns provisioned, libcontainer container created but agent process not yet started). A warm sandbox shaves cold-start off the request hot path. Defaults to 0 (no warm pool). Capped by the worker at MaxExecutionsPerWorker/2. |
workerPoolRef | string | WorkerPoolRef references a WorkerPool resource by name in the same namespace. (required) |
Response
200: OK201: Created202: Accepted
Delete All TaskAgent
DELETE/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/taskagents
Delete collection of TaskAgent
Response
200: OK
Get TaskAgent
GET/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/taskagents/{name}
Get the specified TaskAgent
Response
200: OK
Get TaskAgent
GET/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/taskagents/{name}/invocations
read invocations of the specified TaskAgent
Response
200: OK
Get TaskAgent
GET/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/taskagents/{name}/invoke
connect GET requests to invoke of TaskAgent
Response
200: OK
Get TaskAgent
GET/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/taskagents/{name}/logs
connect GET requests to logs of TaskAgent
Response
200: OK
Get TaskAgent
GET/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/taskagents/{name}/traces
connect GET requests to traces of TaskAgent
Response
200: OK
Create TaskAgent
POST/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/taskagents/{name}/invocations
create invocations of a TaskAgent
Request Body
Spec fields (InvocationSpec):
| Field | Type | Description |
|---|---|---|
identity | InvocationIdentity | Identity is the resolved identity asserted at ingress. |
parentRef | InvocationParentRef | ParentRef identifies the TaskAgent or DaemonAgent that owns this Invocation. Required. (required) |
trigger | InvocationTrigger | Trigger describes how this invocation was initiated. (required) |
Response
200: OK201: Created202: Accepted
Create TaskAgent
POST/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/taskagents/{name}/invoke
connect POST requests to invoke of TaskAgent
Response
200: OK
Replace TaskAgent
PUT/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/taskagents/{name}
Replace the specified TaskAgent
Request Body
Spec fields (TaskAgentSpec):
| Field | Type | Description |
|---|---|---|
delivery | AgentDelivery | Delivery selects how the request payload reaches the agent. Stdin (default) writes a CloudEvents structured-mode JSON envelope to the agent's stdin. Metadata closes stdin and exposes an IMDS-style HTTP server inside the sandbox; the agent fetches via $CLRK_METADATA_URL. |
egressRefs | AgentEgressRef[] | EgressRefs references EgressGateway objects for outbound access. Token budgets are configured on AIProviderRoute, not here. |
identity | AgentIdentity | Identity configures user identity extraction from incoming requests. |
maxConcurrent | integer (int32) | MaxConcurrent caps how many executions of this agent can run simultaneously across all workers. 0 = unlimited. |
resources | ExecutionResources | Resources defines per-execution CPU/memory limits. |
schedule | string | Schedule adds a cron trigger. Does NOT disable HTTP triggering. |
scheduleInput | RawExtension | ScheduleInput is the JSON body sent to the agent on cron triggers. |
state | AgentState | State configures persistent state across executions. |
streaming | AgentStreaming | Streaming configures stdout/stderr streaming behavior. |
template | AgentSandboxRevisionTemplate | Template defines the sandbox revision template. Changes to this field trigger creation of a new AgentSandboxRevision. (required) |
timeout | Duration | Timeout caps how long a single execution can run. Accepts a Go duration string ("100s", "5m", "1h30m"). Defaults to 100s. |
warmPoolIdleTTL | Duration | WarmPoolIdleTTL bounds how long a pre-warmed sandbox can sit in the pool before it is evicted and replaced. Defaults to 10 minutes when unset. Bounds resource-leak accumulation in long-idle agent processes (file descriptors, anon memory, language-runtime caches) at the cost of a cold-fill every IdleTTL when traffic is sparse. |
warmPoolSize | integer (int32) | WarmPoolSize is the per-worker target for pre-Created sandboxes kept Ready (rootfs mounted, TAP+netns provisioned, libcontainer container created but agent process not yet started). A warm sandbox shaves cold-start off the request hot path. Defaults to 0 (no warm pool). Capped by the worker at MaxExecutionsPerWorker/2. |
workerPoolRef | string | WorkerPoolRef references a WorkerPool resource by name in the same namespace. (required) |
Response
200: OK201: Created
Replace TaskAgent
PUT/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/taskagents/{name}/invocations
replace invocations of the specified TaskAgent
Request Body
Spec fields (InvocationSpec):
| Field | Type | Description |
|---|---|---|
identity | InvocationIdentity | Identity is the resolved identity asserted at ingress. |
parentRef | InvocationParentRef | ParentRef identifies the TaskAgent or DaemonAgent that owns this Invocation. Required. (required) |
trigger | InvocationTrigger | Trigger describes how this invocation was initiated. (required) |
Response
200: OK201: Created
Update TaskAgent
PATCH/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/taskagents/{name}
Partially update the specified TaskAgent
Response
200: OK201: Created
Update TaskAgent
PATCH/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/taskagents/{name}/invocations
partially update invocations of the specified TaskAgent
Response
200: OK201: Created
Delete TaskAgent
DELETE/apis/clrk.apoxy.dev/v1alpha1/namespaces/{namespace}/taskagents/{name}
Delete a TaskAgent
Response
200: OK202: Accepted
Schema Reference
AgentDelivery
| Field | Type | Description |
|---|---|---|
mode | string | Mode is Stdin (default) or Metadata. |
AgentEgressRef
| Field | Type | Description |
|---|---|---|
gatewayRef | string | GatewayRef is the name of an EgressGateway in the same namespace. (required) |
AgentIdentity
| Field | Type | Description |
|---|---|---|
extractors | IdentityExtractor[] | Extractors defines one or more identity extraction rules. (required) |
IdentityExtractor
| Field | Type | Description |
|---|---|---|
body | BodyExtractor | Body extracts identity from the request body via JSONPath. |
header | HeaderExtractor | Header extracts identity from an HTTP header. |
jwt | JWTExtractor | JWT extracts identity from a JWT claim. |
type | string | Type selects the extraction method. (required) |
BodyExtractor
| Field | Type | Description |
|---|---|---|
field | string | Field is the identity field to populate. (required) |
jsonPath | string | JSONPath is the JSONPath expression into the request body. (required) |
HeaderExtractor
| Field | Type | Description |
|---|---|---|
field | string | Field is the identity field to populate. (required) |
name | string | Name is the HTTP header name. (required) |
JWTExtractor
| Field | Type | Description |
|---|---|---|
claim | string | Claim is the JWT claim name. (required) |
field | string | Field is the identity field to populate. (required) |
ExecutionResources
| Field | Type | Description |
|---|---|---|
cpu | Quantity | CPU limit for a single execution, enforced via cgroup v2 cpu.max (CFS quota/period). Applies to the entire sandbox process tree. Default "1". |
ephemeralStorage | Quantity | EphemeralStorage limit for a single execution. Currently advisory only — /tmp tmpfs sizing is controlled statically by the worker's OCI spec and per-sandbox cgroup enforcement is not yet wired through for this field. |
memory | Quantity | Memory limit for a single execution, enforced via cgroup v2 memory.max on the entire sandbox process tree. Budget ~32MB on top of the guest's working set for Sentry+gofer baseline overhead; guest pages mirrored into the Sentry's address space count against this limit too. Swap is pinned to zero so the OOM killer fires deterministically at memory.max. Default "512Mi". |
AgentState
| Field | Type | Description |
|---|---|---|
backend | string | Backend is the storage backend. Currently only "sqlite" is supported. |
mountPath | string | MountPath is where state is mounted in the sandbox. Default "/var/clrk/state". Must be a clean absolute path other than "/" and must not overlap with runtime-managed paths (e.g. /proc, /dev, /sys, /tmp, /etc, /usr, /bin, system CA bundles, /etc/resolv.conf). Admission rejects conflicts. |
sizeLimitMB | integer (int32) | SizeLimitMB caps the state storage size in megabytes. Default 100. |
AgentStreaming
| Field | Type | Description |
|---|---|---|
enabled | boolean | Enabled controls whether streaming is active. |
AgentSandboxRevisionTemplate
| Field | Type | Description |
|---|---|---|
spec | AgentSandboxRevisionSpec | Spec is the desired state of the revision. (required) |
AgentSandboxRevisionSpec
| Field | Type | Description |
|---|---|---|
args | string[] | Args are arguments to the entrypoint. |
command | string[] | Command overrides the image entrypoint. |
env | EnvVar[] | Env is a list of environment variables to set in the sandbox. |
image | string | Image is the OCI image reference for the agent. (required) |