> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Hello World

> Simplest Enclave example - your first secure code execution

The simplest possible Enclave example - execute code and get results.

## Basic Example

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { Enclave } from '@enclave-vm/core';

// Create an enclave instance
const enclave = new Enclave();

// Execute code
const result = await enclave.run(`
  const greeting = 'Hello, World!';
  return greeting;
`);

console.log(result.value); // "Hello, World!"

// Clean up
enclave.dispose();
```

## With TypeScript

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { Enclave, ExecutionResult } from '@enclave-vm/core';

async function main(): Promise<void> {
  const enclave = new Enclave({
    securityLevel: 'STRICT',
    timeout: 5000,
  });

  try {
    const result: ExecutionResult = await enclave.run(`
      return 2 + 2;
    `);

    if (result.success) {
      console.log('Result:', result.value); // 4
    } else {
      console.error('Error:', result.error?.message);
    }
  } finally {
    enclave.dispose();
  }
}

main();
```

## With Console Output

A script may use `console` when the enclave has a `consoleHandler`. The handler receives each call as `(level, message)`; the result does not carry the output.

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const lines: string[] = [];

const enclave = new Enclave({
  consoleHandler: (level, message) => {
    lines.push(message);
  },
});

const result = await enclave.run(`
  console.log('Step 1: Initialize');
  const numbers = [1, 2, 3, 4, 5];

  console.log('Step 2: Process');
  const doubled = numbers.map(n => n * 2);

  console.log('Step 3: Complete');
  console.log('Doubled:', doubled);

  return doubled;
`);

// Result
console.log('Return value:', result.value);
// [2, 4, 6, 8, 10]

// Console output, as the handler received it
console.log('Output:', lines);
// Step 1: Initialize
// Step 2: Process
// Step 3: Complete
// Doubled: [2,4,6,8,10]
```

Without a `consoleHandler`, `console` is available only at the `PERMISSIVE` security level; at the other levels a script that uses it fails validation.

## With Variables

Pass data into the execution:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const enclave = new Enclave({
  globals: {
    userName: 'Alice',
    items: [1, 2, 3],
  },
});

const result = await enclave.run(`
  const sum = items.reduce((a, b) => a + b, 0);
  return { user: userName, total: sum };
`);

console.log(result.value);
// { user: 'Alice', total: 6 }
```

## With Tool Calls

Execute code that calls tools:

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const enclave = new Enclave({
  toolHandler: async (name, args) => {
    if (name === 'greet') {
      return `Hello, ${args.name}!`;
    }
    throw new Error(`Unknown tool: ${name}`);
  },
});

const result = await enclave.run(`
  const greeting = await callTool('greet', { name: 'World' });
  return greeting;
`);

console.log(result.value); // "Hello, World!"
```

## Error Handling

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const result = await enclave.run(`
  const data = await callTool('missing', {});
  return data;
`, async (name) => {
  throw new Error(`Unknown tool: ${name}`);
});

if (!result.success) {
  console.log('Failed:', result.error?.code, result.error?.message);
}
```

`run()` does not reject for a failing script: the failure is in the result. `error.message` and `error.name` are plain strings, and an error made inside the sandbox has no `stack`. AgentScript has no `Error` constructor; a script signals a failure by returning a value that says so, or by letting a tool's error pass.

## Complete Example

```ts theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { Enclave } from '@enclave-vm/core';

async function helloWorld() {
  // Create enclave with all options
  const enclave = new Enclave({
    securityLevel: 'STRICT',
    timeout: 10000,
    maxIterations: 1000,
    globals: {
      config: { debug: true },
    },
    toolHandler: async (name, args) => {
      console.log(`Tool called: ${name}`, args);
      return { success: true };
    },
    // Lets the script use console at STRICT; each call arrives as (level, message)
    consoleHandler: (level, message) => console.log(`[script] ${message}`),
  });

  try {
    // Run code
    const result = await enclave.run(`
      console.log('Debug:', config.debug);

      const data = await callTool('echo', { input: 'test' });
      console.log('Tool succeeded:', data.success);

      return 'Hello from Enclave!';
    `);

    // Check result
    if (result.success) {
      console.log('✓ Execution succeeded');
      console.log('Value:', result.value);
      console.log('Duration:', result.stats?.duration, 'ms');
    } else {
      console.log('✗ Execution failed');
      console.log('Error:', result.error);
    }
  } finally {
    // Always clean up
    enclave.dispose();
  }
}

helloWorld();
```

## Expected Output

```
[script] Debug: true
Tool called: echo { input: 'test' }
[script] Tool succeeded: true
✓ Execution succeeded
Value: Hello from Enclave!
Duration: 12 ms
```

## Next Steps

* [Tool Calling](https://docs.agentfront.dev/enclave/examples/tool-calling.md) - More complex tool examples
* [Quickstart](https://docs.agentfront.dev/enclave/getting-started/quickstart.md) - Full setup guide
* [Security Levels](https://docs.agentfront.dev/enclave/core-libraries/enclave-vm/security-levels.md) - Security options


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.