# Guides

> Prereqs: Node 18+, `npm i @treza/sdk`, and environment vars:
>
> ```bash
> export TREZA_BASE_URL=https://app.trezalabs.com
> export WALLET_ADDRESS=0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB
> export GITHUB_ACCESS_TOKEN=gho_xxxxxxxxxxxxxxxxxxxx # optional
> ```

***

### Deploy your first enclave

1. **Pick a provider & region**

```ts
import { TrezaClient } from '@treza/sdk';
const client = new TrezaClient();
const WALLET = process.env.WALLET_ADDRESS!;

const providers = await client.getProviders();
const provider = providers[0];
const region = provider.regions[0];
```

2. **Create the enclave**

```ts
const enclave = await client.createEnclave({
  name: 'hello-enclave',
  description: 'First run',
  region,
  walletAddress: WALLET,
  providerId: provider.id,
  providerConfig: {
    dockerImage: 'hello-world:latest',
    cpuCount: 1,
    memoryMiB: 256,
  },
});
console.log('Enclave:', enclave.id, enclave.status);
```

3. **Tail logs (optional)**

```ts
const logs = await client.getEnclaveLogs(enclave.id, 'application', 50);
console.log('App logs:', (logs.logs.application ?? []).length);
```

***

### Manage lifecycle (pause / resume / terminate)

```ts
import { TrezaClient } from '@treza/sdk';
const client = new TrezaClient();
const WALLET = process.env.WALLET_ADDRESS!;

async function lifecycle(enclaveId: string) {
  const paused = await client.pauseEnclave(enclaveId, WALLET);
  console.log('Paused →', paused.enclave.status);

  const resumed = await client.resumeEnclave(enclaveId, WALLET);
  console.log('Resumed →', resumed.enclave.status);

  const terminated = await client.terminateEnclave(enclaveId, WALLET);
  console.log('Terminated →', terminated.enclave.status);
}
```

**Tips**

* If transitions hang, check `getEnclaveLogs(enclaveId, 'all')` and ensure image/resources are valid.

***

### Guide: View and filter logs

```ts
const all = await client.getEnclaveLogs('enc_123', 'all', 100);
console.log('Types:', Object.keys(all.logs));

const appOnly = await client.getEnclaveLogs('enc_123', 'application', 100);
console.log('App entries:', (appOnly.logs.application ?? []).length);

const errors = await client.getEnclaveLogs('enc_123', 'errors', 50);
console.log('Errors:', (errors.logs.errors ?? []).length);
```

**Common sources**: `all`, `ecs`, `stepfunctions`, `lambda`, `application`, `errors`.

***

### Schedule a task inside an enclave

```ts
const task = await client.createTask({
  name: 'Hourly job',
  description: 'Runs every hour',
  enclaveId: 'enc_123',
  schedule: '0 * * * *',
  walletAddress: process.env.WALLET_ADDRESS!,
});
console.log('Task:', task.id);

// List / update / delete
const tasks = await client.getTasks(process.env.WALLET_ADDRESS!);
const updated = await client.updateTask({ id: task.id, walletAddress: process.env.WALLET_ADDRESS!, schedule: '*/30 * * * *' });
const msg = await client.deleteTask(task.id, process.env.WALLET_ADDRESS!);
```

**Cron basics**

* `0 9 * * *` → 9am daily
* `*/15 * * * *` → every 15 minutes

***

### Create least‑privilege API keys

```ts
const created = await client.createApiKey({
  name: 'prod-readonly',
  permissions: ['enclaves:read', 'tasks:read', 'logs:read'],
  walletAddress: process.env.WALLET_ADDRESS!,
});
console.log('API key (copy now):', created.key);

const keys = await client.getApiKeys(process.env.WALLET_ADDRESS!);
await client.updateApiKey({ id: keys[0].id, walletAddress: process.env.WALLET_ADDRESS!, status: 'active' });
await client.deleteApiKey(keys[0].id, process.env.WALLET_ADDRESS!);
```

**Good defaults**

* Separate keys per environment (dev/stage/prod)
* Narrow permissions; rotate regularly

***

### Connect a GitHub repo (optional)

```ts
// Start OAuth
const { authUrl } = await client.getGitHubAuthUrl('state-123');
console.log('Open:', authUrl);

// After callback → exchange code
const token = await client.exchangeGitHubCode({ code: 'code-from-callback', state: 'state-123' });

// Browse repos/branches
const repos = await client.getGitHubRepositories(token.access_token);
const branches = await client.getRepositoryBranches({ accessToken: token.access_token, repository: repos.repositories[0].fullName });

// Link to an enclave
await client.updateEnclave({
  id: 'enc_123',
  walletAddress: process.env.WALLET_ADDRESS!,
  githubConnection: { isConnected: true, selectedRepo: repos.repositories[0].fullName, selectedBranch: branches.branches[0].name },
});
```

**Notes**

* Store `access_token` securely; do not hardcode.

***

### Use Docker images & tags

```ts
const search = await client.searchDockerImages('node');
console.log('Top results:', search.results.slice(0, 3).map(r => r.name));

const tags = await client.getDockerTags('library/node');
console.log('Recent tags:', tags.tags.slice(0, 5).map(t => t.name));

// In createEnclave → providerConfig.dockerImage = 'library/node:20-alpine'
```

**Gotchas**

* Official images often require the `library/` prefix.
* Ensure the tag exists; otherwise deployments will fail early.

***

### Troubleshooting

* **401/403**: wallet doesn’t own the resource
* **404**: wrong `enclaveId` or different wallet scope
* **Lifecycle stuck**: check provider logs and `providerConfig`
* **Docker image not found**: verify repo & tag via Docker helpers

***

### See also

* [**Examples**](/developers/examples.md)  – copy‑paste runnable snippets
* [**API Reference** ](/developers/rest-api.md)– complete type & method docs
* [**Concepts**](/getting-started/concepts.md) → *Providers, Enclaves, Lifecycle*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.trezalabs.com/developers/guides.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.