---
title: "TEE Integration"
description: "Hardware-level security for agents that handle sensitive data"
---

## Why TEE?

Your agent handles API keys, user data, maybe crypto wallets. How do users know you're not logging their secrets?

**TEE (Trusted Execution Environment)** provides cryptographic proof that your code runs exactly as published - no modifications, no backdoors. Users can verify your agent's integrity before trusting it.

<Tip>
  **TEE is optional.** Most agents don't need it. Use TEE when you need to prove
  trustworthiness to users who can't just take your word for it.
</Tip>

## What TEE Gives You

TEE integration allows your ElizaOS agents to run in secure enclaves with:

- **Remote attestation**: Cryptographic proof of code integrity
- **Secure key derivation**: Keys derived within the enclave
- **Verifiable execution**: Third parties can verify agent behavior

## TEE Modes

```typescript
enum TEEMode {
  OFF = "OFF", // TEE disabled
  LOCAL = "LOCAL", // Local development with simulator
  DOCKER = "DOCKER", // Docker development with simulator
  PRODUCTION = "PRODUCTION", // Production with real TEE hardware
}
```

## Quick Start

### 1. Create a Project

```bash
elizaos create my-tee-agent --template project
cd my-tee-agent
bun install
```

### 2. Configure TEE Settings

```env .env
TEE_MODE=LOCAL
TEE_VENDOR=phala
WALLET_SECRET_SALT=your-secret-salt-min-8-chars
```

### 3. Start in TEE Mode

```bash
bun run dev
```

## Configuration

### Environment Variables

| Variable             | Description                               | Required |
| -------------------- | ----------------------------------------- | -------- |
| `TEE_MODE`           | `OFF`, `LOCAL`, `DOCKER`, or `PRODUCTION` | Yes      |
| `TEE_VENDOR`         | TEE provider (`phala`)                    | Yes      |
| `WALLET_SECRET_SALT` | Secret for key derivation (8-128 chars)   | Yes      |

### Character Configuration

```typescript
export const character: Character = {
  name: "SecureAgent",
  plugins: [
    "@elizaos/plugin-tee", // Add TEE plugin
  ],
  settings: {
    secrets: {
      TEE_MODE: "PRODUCTION",
      TEE_VENDOR: "phala",
      WALLET_SECRET_SALT: process.env.WALLET_SECRET_SALT,
    },
  },
};
```

## TEE Types

### TeeAgent

Represents an agent registered in the TEE:

```typescript
interface TeeAgent {
  id: string; // Registration record ID
  agentId: string; // Core agent identifier
  agentName: string; // Human-readable name
  createdAt: number; // Registration timestamp
  publicKey: string; // TEE instance public key
  attestation: string; // Attestation document
}
```

### Remote Attestation

```typescript
interface RemoteAttestationQuote {
  quote: string; // Base64-encoded attestation quote
  timestamp: number; // Quote generation time
}

interface RemoteAttestationMessage {
  agentId: string;
  timestamp: number;
  message: {
    entityId: string;
    roomId: string;
    content: string;
  };
}

interface DeriveKeyAttestationData {
  agentId: string;
  publicKey: string;
  subject?: string;
}
```

## TEE Providers

ElizaOS supports multiple TEE providers. Keep provider-specific deployment commands in your generated project scripts or deployment automation.

### Phala Network

Primary TEE provider using Intel TDX:

```bash
# Login to Phala Cloud
elizaos tee phala auth login <api-key>

# Deploy to Phala
elizaos tee phala cvms create --name my-agent --compose ./docker-compose.yml

# Check status
elizaos tee phala cvms list
```

### Eigen Infrastructure

```bash
elizaos tee eigen deploy
```

## API Endpoints

### Get TEE Status

```bash
GET /api/tee/status
```

Response:

```json
{
  "status": "active",
  "tee_enabled": true,
  "vendor": "phala"
}
```

### Get TEE Agents

```bash
GET /api/tee/agents
```

Response:

```json
{
  "agents": [
    {
      "id": "...",
      "agentId": "...",
      "agentName": "SecureAgent",
      "publicKey": "...",
      "attestation": "..."
    }
  ],
  "attestation": "..."
}
```

## Key Derivation

TEE enables secure key derivation within the enclave:

```typescript
// Keys are derived from the enclave's secure environment
const deriveEcdsaKeypair = (deriveKeyResponse: DeriveKeyResponse): PrivateKeyAccount
const deriveEd25519Keypair = (deriveKeyResponse: DeriveKeyResponse): Keypair
```

Keys derived in TEE:

- Cannot be extracted from the enclave
- Are tied to the specific enclave instance
- Can be verified through attestation

## Security Considerations

<Warning>
  - **Secret salt**: Use a strong, unique salt for each deployment -
  **Attestation verification**: Always verify attestation quotes in production -
  **Key rotation**: Plan for key rotation when updating enclave code
</Warning>

### Best Practices

1. **Development**: Use `TEE_MODE=LOCAL` for testing
2. **Staging**: Use `TEE_MODE=DOCKER` for integration tests
3. **Production**: Use `TEE_MODE=PRODUCTION` with real hardware
4. **Secrets**: Never commit `WALLET_SECRET_SALT` to version control

## See Also

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="terminal" href="/cli-reference/overview">
    Simplified workspace CLI commands
  </Card>
  <Card title="Deploy a Project" icon="rocket" href="/guides/deploy-a-project">
    General deployment guide
  </Card>
  <Card title="Services" icon="server" href="/runtime/services">
    Background services and integrations
  </Card>
  <Card
    title="Phala Documentation"
    icon="book"
    href="https://docs.phala.network/"
  >
    Official Phala Cloud docs
  </Card>
</CardGroup>