# <Script />

Execute one literal command or resolved shell source on the host or through the active Sandbox runtime.
Canonical: https://agent-markup-language.com/docs/reference/primitives/script/
Documentation index: https://agent-markup-language.com/docs/
Complete documentation: https://agent-markup-language.com/docs/llms.txt

`<Script />` runs a trusted host process from the runtime cwd when no [`<Sandbox />`](https://agent-markup-language.com/docs/reference/primitives/sandbox/) is active. Inside a Sandbox, it uses that Sandbox runtime and never falls back to the host.

```tsx
import { AmlRuntime, Script } from "@aml-jsx/sdk"

const runtime = new AmlRuntime({ cwd: "/absolute/path/to/project" })
const output = await runtime.evaluate(<Script cwd="apps/cli" command="node" args={["--version"]} timeoutMs={10_000} />)
```

## Execution location

| Placement          | Default cwd                                            | Explicit `cwd` base     |
| ------------------ | ------------------------------------------------------ | ----------------------- |
| No active Sandbox  | `AmlRuntimeOptions.cwd`, defaulting to `process.cwd()` | `AmlRuntimeOptions.cwd` |
| Inside `<Sandbox>` | The effective Sandbox cwd                              | The active Sandbox root |

`cwd` is a portable relative forward-slash path shared by both forms. AML rejects absolute paths, backslashes, and parent traversal. The target directory must already exist. Host execution is deliberately unconfined: `cwd` changes the process starting directory, but the process still inherits the AML host identity and environment and may access paths outside it. Use host execution only for trusted authored automation. Add an enforcing Sandbox whenever the command or resolved source is model-generated, user-supplied, or otherwise untrusted.

## Two forms

| Form               | Required props                   | Child content               | Runtime call                                      |
| ------------------ | -------------------------------- | --------------------------- | ------------------------------------------------- |
| Literal command    | `command`, optional `args`       | not allowed                 | `exec(command, args)` without shell interpolation |
| Interpreted source | `shell="sh" \| "bash" \| "node"` | required non-empty AML text | `exec(shell, interpreter arguments)`              |

Both forms accept `cwd` and `timeoutMs`; `timeoutMs` must be a positive safe integer. `args` is valid only with `command`; command form accepts no children. TypeScript models these as disjoint prop forms, and the runtime preserves the same validation for plain JavaScript.

```tsx
<Sandbox provider={sandbox} access="read-write">
  <Script cwd="packages/worker" shell="node" timeoutMs={30_000}>
    {`console.log(JSON.stringify({ ok: true }))`}
  </Script>
</Sandbox>
```

## Result and failures

Successful standard output becomes AML text for later composition. A non-zero exit code rejects with `EvaluationError` and includes trimmed stderr detail when available. AML bounds, cancels, and reaps host execution directly; inside a Sandbox, its provider owns those runtime details. Trace spans report `environment="host"` or `environment="sandbox"`.

Generated source is executable authority. If [`<Agent />`](https://agent-markup-language.com/docs/reference/primitives/agent/) produces the children of `<Script />`, treat that output as untrusted and select an enforcing Sandbox with tight credentials, filesystem access, network policy, and resource limits.

See the [generated diagnostic recipe](https://agent-markup-language.com/docs/cookbook/generated-diagnostic/) and the [Sandbox provider guides](https://agent-markup-language.com/docs/providers/sandboxes/).