Sandboxesクイックスタート

Sandboxes クイックスタート

サンドボックスを起動し、その中でコードを実行し、ポートを公開して、Lizard SDK で一時停止します。

インストール

# JavaScript / TypeScript
npm install @lizard-build/sdk
 
# Python
pip install lizard-sdk

認証

Sandboxes は API キー で認証します。ダッシュボードの サンドボックス → 開始する → 新しいAPIキー で作成してください。表示されるのは一度だけなので、すぐにコピーしてください。

環境変数に設定すると、SDK が自動的に読み取ります:

export LIZARD_API_KEY="<your-api-key>"

明示的に渡すこともできます: Sandbox.create('base', { apiKey, project }).

プロジェクトを選ぶ

すべてのサンドボックスはプロジェクトに属します。利用量はプロジェクトごとに計測されるため、指定しないと API は作成を拒否します。プロジェクトは ID、slug、または名前で指定します。

Lizard クライアントは 1 つのプロジェクトに固定されるため、指定は一度だけで済みます:

import { Lizard } from '@lizard-build/sdk';
 
const lizard = new Lizard({ project: 'my-project' });
const sandbox = await lizard.create('base');
from lizard import Lizard
 
lizard = Lizard(project="my-project")
sandbox = lizard.create("base")

クライアントを保持したくない場合は、Sandbox.create でも同じ project オプションを使えます。以下では両方の形式を使います。

最初の sandbox

JavaScript / TypeScript

import { Sandbox } from '@lizard-build/sdk';
 
// Boot from a template (default: 'base') in a project
const sandbox = await Sandbox.create('base', { project: 'my-project' });
 
// Run a command and wait for it to finish
try {
  const result = await sandbox.process.exec('node -e "console.log(2 ** 10)"');
  console.log(result.stdout);     // 1024
  console.log(result.exitCode);   // 0
} finally {
  await sandbox.kill();
}

Python

from lizard import Sandbox
 
sandbox = Sandbox.create("base", project="my-project")
 
# exec_ (trailing underscore) because `exec` is reserved in Python
try:
    result = sandbox.process.exec_("python -c 'print(2 ** 10)'")
    print(result.stdout)     # 1024
finally:
    sandbox.kill()

process.exec は { stdout, stderr, exitCode } を返します。コマンドの完了を待機します。長時間実行するプロセスをバックグラウンドで動かすには、末尾に & を付けてください。

ファイルを扱う

sandbox.fs は micro-VM filesystem に直接読み書きし、必要に応じて親ディレクトリを作成します。

await sandbox.fs.write('/app/server.js', `
  const http = require('http');
  http.createServer((_, res) => res.end('hello from Lizard')).listen(3000);
`);
 
const src = await sandbox.fs.read('/app/server.js');
const entries = await sandbox.fs.list('/app');   // [{ name, path, type, size }]
await sandbox.fs.makeDir('/app/data');
await sandbox.fs.remove('/app/old.log');
メソッド説明
fs.write(path, data)ファイルを書き込む — string または bytes; 親ディレクトリも作成
fs.read(path)ファイルを UTF-8 string として読み込む
fs.list(path)ディレクトリエントリを一覧表示
fs.makeDir(path)ディレクトリと不足している親を作成
fs.remove(path)ファイルまたはディレクトリを削除

ポートを公開する

サンドボックス内で HTTP サーバーを起動し、それに対する公開 HTTPS URL を取得します。トンネリングは不要です。

await sandbox.process.exec('node /app/server.js &');   // listen on :3000
 
const host = await sandbox.getHost(3000);
console.log(`Live at https://${host}`);
// https://<sandboxId>-3000.sandbox.<region>.onlizard.com

getHost(port) はそのポートへのルートを登録し、hostname を返します。URL は公開され、TLS 終端されています。再度削除するにはダッシュボードを使用してください。

一時停止と再開

一時停止するとゲストの vCPU は凍結され、現在の状態はホストメモリに保持されます。永続的なスナップショットは書き込みません。元の期限を超えてセッションを保持する前に、一時停止と期限切れの問題 を確認してください。

// Set the environment up once
const sandbox = await Sandbox.create('base', { project: 'my-project' });
await sandbox.process.exec('npm install -g some-heavy-toolchain');
const id = sandbox.sandboxId;
 
await sandbox.pause();          // freeze the guest; see the lifecycle issue below
 
// …minutes or hours later, from anywhere:
const resumed = await Sandbox.connect(id);   // resumes guest state still held by the host
await resumed.process.exec('some-heavy-toolchain --version');   // already installed
await resumed.kill();

Sandbox.connect(id) は一時停止された sandbox を自動的に再開します。すでに保持しているハンドルに対して sandbox.resume() を呼び出すこともできます。

Python

sandbox = Sandbox.create("base", project="my-project")
sandbox.process.exec_("pip install numpy pandas")
sandbox_id = sandbox.sandbox_id
sandbox.pause()
 
resumed = Sandbox.connect(sandbox_id)   # resumes guest state still held by the host
resumed.process.exec_("python -c 'import numpy'")
resumed.kill()

タイムアウト

sandbox に正のタイムアウトがある場合、その存続期間を過ぎると期限切れになります。SDK のデフォルトは 5 分です。作成時に timeoutMs: 0 を指定すると有効期限を無効化できます。明示的な上限を設定し、タスク終了時に sandbox を解放してください。実行中のサンドボックスは次で調整できます:

const sandbox = await Sandbox.create('base', { project: 'my-project', timeoutMs: 10 * 60 * 1000 }); // 10 min
await sandbox.setTimeout(30 * 60 * 1000);   // extend to 30 min from now

一時停止は残りの実行時間を凍結することを意図していますが、現在の lifecycle issue ではバックエンドのリリース確認が必要です。データ保持のために無制限の一時停止を当てにしないでください。

サンドボックスを管理する

const sandbox = await Sandbox.create('base', { project: 'my-project' });
const info = await sandbox.getInfo();     // { sandboxId, template, startedAt, endAt, … }
 
const all = await Sandbox.list();         // every running sandbox for this account
await sandbox.kill();

完全な例

スクリプトを書き込み、それを実行し、結果を配信し、後で呼び出すためにゲストを一時停止するエージェント:

import { Sandbox } from '@lizard-build/sdk';
 
const sandbox = await Sandbox.create('base', { project: 'my-project', timeoutMs: 15 * 60 * 1000 });
 
try {
  await sandbox.fs.write('/app/app.js', `
    const http = require('http');
    http.createServer((_, res) => res.end('ok')).listen(3000);
  `);
  await sandbox.process.exec('node /app/app.js &');
 
  const host = await sandbox.getHost(3000);
  const res = await fetch(`https://${host}`);
  console.log(await res.text());          // ok
 
  await sandbox.pause();                   // resume later with Sandbox.connect(sandbox.sandboxId)
} catch (err) {
  await sandbox.kill();
  throw err;
}

次のステップ

概要SDK リファレンス