# Disk



Disk provides persistent file storage with paths, metadata, and secure download URLs. Projects with [end-to-end encryption](/security/encryption) enabled will automatically encrypt all disk files at rest.

<Card title="Agentic Disk SDK" icon="box" href="/tool/disk_tools">
  Bring filesystem to your agent with one-line code.
</Card>

## Quick Start [#quick-start]

<Steps>
  <Step title="Create a disk">
    <CodeGroup>
      ```python title="Python"
      import os
      from acontext import AcontextClient, FileUpload

      client = AcontextClient(api_key=os.getenv("ACONTEXT_API_KEY"))
      disk = client.disks.create()
      ```

      ```typescript title="TypeScript"
      import { AcontextClient, FileUpload } from '@acontext/acontext';

      const client = new AcontextClient({
          apiKey: process.env.ACONTEXT_API_KEY,
      });
      const disk = await client.disks.create();
      ```
    </CodeGroup>
  </Step>

  <Step title="Upload a file">
    <CodeGroup>
      ```python title="Python"
      artifact = client.disks.artifacts.upsert(
          disk.id,
          file=FileUpload(filename="notes.md", content=b"# Meeting Notes"),
          file_path="/documents/",
          meta={"author": "alice"}
      )
      ```

      ```typescript title="TypeScript"
      const artifact = await client.disks.artifacts.upsert(disk.id, {
          file: new FileUpload({
              filename: "notes.md",
              content: Buffer.from("# Meeting Notes"),
          }),
          filePath: "/documents/",
          meta: { author: "alice" },
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Get file with URL">
    <CodeGroup>
      ```python title="Python"
      result = client.disks.artifacts.get(
          disk.id,
          file_path="/documents/",
          filename="notes.md",
          with_public_url=True,
          with_content=True
      )
      print(result.public_url)
      print(result.content.raw)
      ```

      ```typescript title="TypeScript"
      const result = await client.disks.artifacts.get(disk.id, {
          filePath: "/documents/",
          filename: "notes.md",
          withPublicUrl: true,
          withContent: true,
      });
      console.log(result.publicUrl);
      console.log(result.content?.raw);
      ```
    </CodeGroup>
  </Step>

  <Step title="List files">
    <CodeGroup>
      ```python title="Python"
      result = client.disks.artifacts.list(disk.id, path="/documents/")
      for artifact in result.artifacts:
          print(f"{artifact.filename} - {artifact.meta}")
      ```

      ```typescript title="TypeScript"
      const listResult = await client.disks.artifacts.list(disk.id, { path: "/documents/" });
      for (const artifact of listResult.artifacts) {
          console.log(`${artifact.filename} - ${JSON.stringify(artifact.meta)}`);
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Search files">
    <CodeGroup>
      ```python title="Python"
      # Search content with regex
      results = client.disks.artifacts.grep_artifacts(disk.id, query="TODO.*")

      # Find by path pattern
      results = client.disks.artifacts.glob_artifacts(disk.id, query="**/*.md")
      ```

      ```typescript title="TypeScript"
      // Search content with regex
      const grepResults = await client.disks.artifacts.grepArtifacts(disk.id, { query: "TODO.*" });

      // Find by path pattern
      const globResults = await client.disks.artifacts.globArtifacts(disk.id, { query: "**/*.md" });
      ```
    </CodeGroup>
  </Step>

  <Step title="Update metadata">
    <CodeGroup>
      ```python title="Python"
      client.disks.artifacts.update(
          disk.id,
          file_path="/documents/",
          filename="notes.md",
          meta={"author": "alice", "reviewed": True}
      )
      ```

      ```typescript title="TypeScript"
      await client.disks.artifacts.update(disk.id, {
          filePath: "/documents/",
          filename: "notes.md",
          meta: { author: "alice", reviewed: true },
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Clean up">
    <CodeGroup>
      ```python title="Python"
      client.disks.artifacts.delete(disk.id, file_path="/documents/", filename="notes.md")
      client.disks.delete(disk.id)
      ```

      ```typescript title="TypeScript"
      await client.disks.artifacts.delete(disk.id, { filePath: "/documents/", filename: "notes.md" });
      await client.disks.delete(disk.id);
      ```
    </CodeGroup>
  </Step>
</Steps>

## Complete Example [#complete-example]

<Accordion title="Full workflow">
  <CodeGroup>
    ```python title="Python"
    import os
    from acontext import AcontextClient, FileUpload

    client = AcontextClient(api_key=os.getenv("ACONTEXT_API_KEY"))

    # Create disk
    disk = client.disks.create()

    # Upload file
    artifact = client.disks.artifacts.upsert(
        disk.id,
        file=FileUpload(filename="notes.md", content=b"# Meeting Notes\nQ4 goals discussed."),
        file_path="/meetings/",
        meta={"date": "2024-01-15"}
    )

    # Get with URL
    result = client.disks.artifacts.get(
        disk.id, file_path="/meetings/", filename="notes.md",
        with_public_url=True
    )
    print(f"URL: {result.public_url}")

    # List files
    files = client.disks.artifacts.list(disk.id, path="/meetings/")
    print(f"Found {len(files.artifacts)} files")

    # Cleanup
    client.disks.delete(disk.id)
    ```

    ```typescript title="TypeScript"
    import { AcontextClient, FileUpload } from '@acontext/acontext';

    const client = new AcontextClient({
        apiKey: process.env.ACONTEXT_API_KEY,
    });

    // Create disk
    const disk = await client.disks.create();

    // Upload file
    const artifact = await client.disks.artifacts.upsert(disk.id, {
        file: new FileUpload({
            filename: "notes.md",
            content: Buffer.from("# Meeting Notes\nQ4 goals discussed."),
        }),
        filePath: "/meetings/",
        meta: { date: "2024-01-15" },
    });

    // Get with URL
    const result = await client.disks.artifacts.get(disk.id, {
        filePath: "/meetings/",
        filename: "notes.md",
        withPublicUrl: true,
    });
    console.log(`URL: ${result.publicUrl}`);

    // List files
    const files = await client.disks.artifacts.list(disk.id, { path: "/meetings/" });
    console.log(`Found ${files.artifacts.length} files`);

    // Cleanup
    await client.disks.delete(disk.id);
    ```
  </CodeGroup>
</Accordion>

## Next Steps [#next-steps]

<CardGroup cols="2">
  <Card title="Sandbox" icon="terminal" href="/store/sandbox">
    Execute code with disk file transfer
  </Card>

  <Card title="Dashboard" icon="chart-simple" href="/observe/dashboard">
    View artifacts in the dashboard
  </Card>
</CardGroup>