@ory/argus 0.5.0 → 0.6.1

package/assets/skills/ory-e2b-sandbox/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: ory-e2b-sandbox
+description: Scaffold an E2B (e2b.dev) sandbox template that boots with {{PKG}} preinstalled, so every Claude/Codex/Gemini/OpenClaw/OpenCode session running inside the sandbox is gated by Ory auth, permissions, and tracing without any per-sandbox setup. Use when the user asks to "create an E2B sandbox with Ory agent security", "build an E2B template with the Ory plugin", "make an E2B image that includes Ory auth", or any close variant. The skill generates the template files in the user's project — it does not deploy them.
+---
+
+# E2B sandbox with Ory agent security
+
+You are helping the user scaffold an [E2B](https://e2b.dev) sandbox template
+that preinstalls and registers the {{PKG}} plugin. The resulting template
+publishes a named image; every `Sandbox.create("<tag>")` call from their SDK
+gets a runtime where the agent's tool calls are already authenticated against
+Ory Identities, authorized against Ory Permissions, and emitted as trace
+spans — with **no** install step at sandbox boot.
+
+This skill carries the full workflow and the file contents. You generate the
+files in the user's repo; the user runs the build.
+
+> **Precondition:** the user has (or will obtain) an `E2B_API_KEY` and has
+> installed the E2B CLI / SDK (`npm install e2b dotenv`). If they haven't, point
+> them at <https://e2b.dev/docs> and stop — do not fabricate credentials.
+
+## Step 1 — Confirm the target
+
+Before writing files, confirm with the user:
+
+1. **Where in their repo should the integration live?** A common choice is
+   `integrations/e2b/` at the repo root. Use that unless they say otherwise.
+2. **Template tag.** Default to `agent-ory` (e.g. `claude-code-ory`,
+   `codex-ory`). Operators will reference this string in `Sandbox.create()`.
+3. **Will the sandbox have network access to Ory?** It must — the plugin makes
+   live API calls to `ORY_PROJECT_URL` from inside the sandbox.
+
+If the user is targeting an in-process harness (OpenClaw, OpenCode), the host
+binary that loads the plugin must also be available inside the sandbox. Flag
+this and ask how they ship that binary today — usually `npm install` of a
+project that already depends on the harness runtime.
+
+## Step 2 — Generate the files
+
+Create these four files at the chosen location (the example uses
+`integrations/e2b/`).
+
+### `integrations/e2b/template.ts`
+
+```ts
+import { Template } from "e2b";
+
+export const template = Template()
+  .fromUbuntuImage("22.04")
+  .aptInstall(["curl", "ca-certificates", "git", "python3"])
+
+  // Node.js 20 (NodeSource)
+  .runCmd("curl -fsSL https://deb.nodesource.com/setup_20.x | bash -")
+  .aptInstall(["nodejs"])
+
+  // Install the harness CLI globally. Replace `@anthropic-ai/claude-code` with
+  // the binary that hosts the Ory plugin in this sandbox (e.g. the Codex or
+  // Gemini CLI). For in-process harnesses (openclaw, opencode), `npm install`
+  // the harness runtime here instead and ensure its entrypoint is on PATH.
+  .npmInstall(["@anthropic-ai/claude-code"], { g: true })
+
+  // Install the Ory plugin into the harness's discovery location.
+  .setWorkdir("/root")
+  .runCmd("{{NPX}} install")
+
+  // Sandbox runtime defaults. Per-tenant secrets (project URL, tokens, client
+  // IDs) MUST be passed at Sandbox.create() time, never baked into the image.
+  .setEnvs({
+    ORY_AUTH_GATE: "1",
+    ORY_PERMISSION_MODE: "observe",
+    ORY_PERMISSION_NAMESPACE: "AgentTools",
+    ORY_AGENT_DEBUG: "true",
+    ORY_AGENT_LOG_FILE: "/root/ory-agent-debug.log",
+  })
+
+  .setWorkdir("/workspace");
+```
+
+### `integrations/e2b/build.prod.ts`
+
+```ts
+import "dotenv/config";
+import { Template, defaultBuildLogger } from "e2b";
+import { template } from "./template";
+
+await Template.build(template, "agent-ory", {
+  cpuCount: 2,
+  memoryMB: 4096,
+  onBuildLogs: defaultBuildLogger(),
+});
+```
+
+### `integrations/e2b/build.dev.ts`
+
+```ts
+import "dotenv/config";
+import { Template, defaultBuildLogger } from "e2b";
+import { template } from "./template";
+
+await Template.build(template, "agent-ory-dev", {
+  cpuCount: 2,
+  memoryMB: 4096,
+  skipCache: true,
+  onBuildLogs: defaultBuildLogger(),
+});
+```
+
+### `integrations/e2b/.env.example`
+
+```
+# E2B credentials — required to build and run templates.
+E2B_API_KEY=e2b_***
+
+# Per-tenant Ory wiring — passed to Sandbox.create() at runtime, NOT baked into
+# the template. Listed here so operators know what to plumb through.
+ORY_PROJECT_URL=https://<slug>.projects.oryapis.com
+ORY_OAUTH2_CLIENT_ID=
+ORY_USER_SESSION_TOKEN=
+# Optional: pin a static agent identity instead of DCR.
+# ORY_AGENT_API_KEY=
+```
+
+### `integrations/e2b/package.json`
+
+```json
+{
+  "name": "ory-e2b-integration",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build:dev": "tsx build.dev.ts",
+    "build:prod": "tsx build.prod.ts"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.5",
+    "e2b": "^2.3.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^6.0.2"
+  }
+}
+```
+
+### `integrations/e2b/README.md`
+
+Generate a README that captures:
+
+- What the template provides (harness CLI + {{PKG}} preinstalled, runtime
+  defaults baked in, secrets supplied at sandbox creation).
+- The build flow: `npm install`, `npx e2b auth login` once, then
+  `npm run build:prod`.
+- A `Sandbox.create("agent-ory", { envs: { ... } })` example showing which env
+  vars to inject at runtime (`ORY_PROJECT_URL`, `ORY_OAUTH2_CLIENT_ID`,
+  `ORY_USER_SESSION_TOKEN` or `ORY_USER_OAUTH2_TOKEN`, optional
+  `ORY_AGENT_API_KEY`).
+- A pointer to {{REF_AUTH_SETUP}} for full env-var coverage and to
+  {{REF_LOCAL_DEV}} for testing the same plugin locally before publishing the
+  template.
+
+## Step 3 — Build and publish
+
+Walk the user through:
+
+```bash
+cd integrations/e2b
+cp .env.example .env        # then fill in E2B_API_KEY
+npm install
+npx e2b auth login          # one-time
+npm run build:prod          # publishes the tag chosen in Step 1
+```
+
+Manage the published template via the E2B CLI:
+
+```bash
+npx e2b template list
+npx e2b template delete <tag>
+```
+
+## Step 4 — Use the sandbox
+
+Show the user the minimal SDK call once their template is live:
+
+```ts
+import { Sandbox } from "e2b";
+
+const sbx = await Sandbox.create("agent-ory", {
+  envs: {
+    ORY_PROJECT_URL: process.env.ORY_PROJECT_URL!,
+    ORY_OAUTH2_CLIENT_ID: process.env.ORY_OAUTH2_CLIENT_ID!,
+    // Pre-supply a user token so the headless sandbox skips PKCE.
+    ORY_USER_SESSION_TOKEN: process.env.ORY_USER_SESSION_TOKEN!,
+  },
+});
+
+await sbx.commands.run("{{BIN}} --version");  // sanity check
+```
+
+Sandboxes are headless, so the user **must** pre-supply
+`ORY_USER_SESSION_TOKEN` or `ORY_USER_OAUTH2_TOKEN` — otherwise the auth gate's
+PKCE browser flow has no target and hangs. See {{REF_AUTH_SETUP}} for the full
+env-var matrix.
+
+## Step 5 — Promotion path
+
+The template ships with `ORY_PERMISSION_MODE=observe` baked in so first-run
+sandboxes never block. To promote a sandbox to hard enforcement without
+rebuilding the template, either pass `ORY_PERMISSION_MODE=enforce` at
+`Sandbox.create()` time, or run `{{NPX}} permissions enforce` inside a running
+sandbox. Run `{{NPX}} permissions bootstrap` first on a fresh Ory project so
+the `use` tuples exist before enforcement turns on.
+
+## What this skill does NOT do
+
+- It does not build or publish the template — the user runs the build, so
+  they can see logs and own the resulting tag.
+- It does not bake secrets into the image. `ORY_PROJECT_URL`, OAuth client IDs,
+  and any tokens are always passed at `Sandbox.create()` time.
+- It does not pin the harness CLI version inside the template. If the user
+  wants reproducibility, swap the unpinned `npmInstall([...])` for a tagged
+  version (e.g. `["@anthropic-ai/claude-code@1.2.3"]`) before building.
+- It does not modify the user's Ory project. Use {{REF_AUTH_SETUP}} to
+  provision the OAuth2 client and namespaces the sandbox will need.

package/dist/skills.d.ts

@@ -2,9 +2,9 @@
  * Canonical Ory agent skills and commands.
  *
  * The skill playbooks (auth-setup, login-flow, social-login, local-dev,
- * permissions-onboarding, contribute-integration, build-integration) and the
- * local-stack commands (local-up, local-down) live once, as token-bearing
- * templates under `packages/core/assets/`. Every harness plugin renders them
+ * permissions-onboarding, contribute-integration, build-integration,
+ * e2b-sandbox) and the local-stack commands (local-up, local-down) live once,
+ * as token-bearing templates under `packages/core/assets/`. Every harness plugin renders them
  * through {@link renderOrySkills} / {@link renderOryCommands}, substituting the
  * harness's CLI binary, package name, and the way it references sibling skills
  * and commands. Plugins then write the rendered docs into whatever location

package/dist/skills.js

@@ -3,9 +3,9 @@
  * Canonical Ory agent skills and commands.
  *
  * The skill playbooks (auth-setup, login-flow, social-login, local-dev,
- * permissions-onboarding, contribute-integration, build-integration) and the
- * local-stack commands (local-up, local-down) live once, as token-bearing
- * templates under `packages/core/assets/`. Every harness plugin renders them
+ * permissions-onboarding, contribute-integration, build-integration,
+ * e2b-sandbox) and the local-stack commands (local-up, local-down) live once,
+ * as token-bearing templates under `packages/core/assets/`. Every harness plugin renders them
  * through {@link renderOrySkills} / {@link renderOryCommands}, substituting the
  * harness's CLI binary, package name, and the way it references sibling skills
  * and commands. Plugins then write the rendered docs into whatever location
@@ -81,6 +81,11 @@ const SKILL_SOURCES = [
         name: "ory-build-integration",
         file: "skills/ory-build-integration/SKILL.md",
     },
+    {
+        id: "e2b-sandbox",
+        name: "ory-e2b-sandbox",
+        file: "skills/ory-e2b-sandbox/SKILL.md",
+    },
 ];
 const COMMAND_SOURCES = [
     {
@@ -112,9 +117,10 @@ function code(value) {
  * Build the token substitution map for a harness. The reference style differs:
  *
  * - Claude Code addresses sibling skills as `/project:<name>` and the commands
- *   as `/ory:local-up`.
- * - Gemini CLI and OpenCode expose the commands as real slash commands
- *   (`/ory:local-up`) but model-invoke skills by name.
+ *   under the plugin's own namespace (`/ory-agent-plugin:local-up`), because
+ *   Claude Code namespaces plugin commands by the plugin's `plugin.json` name.
+ * - Gemini CLI and OpenCode expose the commands as real slash commands under
+ *   the `ory` namespace (`/ory:local-up`) but model-invoke skills by name.
  * - Codex and OpenClaw render the commands as user-invocable skills, so both
  *   skills and commands are referenced by their bare skill name.
  */
@@ -124,6 +130,9 @@ function buildProfile(harness, opts) {
     let localDown;
     switch (harness) {
         case "claude-code":
+            localUp = code("/ory-agent-plugin:local-up");
+            localDown = code("/ory-agent-plugin:local-down");
+            break;
         case "gemini-cli":
         case "opencode":
             localUp = code("/ory:local-up");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/argus",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Ory Argus: the core API for building authentication, authorization, and audit into AI agent harness plugins, extensions, and custom integrations",
   "license": "Apache-2.0",
   "homepage": "https://ory.com",