> ## Documentation Index
> Fetch the complete documentation index at: https://novita.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Montar bucket de armazenamento de objetos no sandbox

export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/docs/pt-BR/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

Cada instância de sandbox é provisionada, por padrão, com 20 GB de armazenamento efêmero em disco do sistema para operações temporárias com dados. <u>Após o encerramento ou timeout do sandbox, todos os dados dentro desse espaço de armazenamento são automaticamente expurgados</u>. Consequentemente, dados persistentes que exigem retenção de longo prazo devem ser armazenados em serviços externos de armazenamento em nuvem.

<Tip>
  As especificações de alocação de armazenamento do sandbox estão sujeitas a alterações. Consulte a documentação de [Pricing](/docs/pt-BR/guides/sandbox-pricing) para ver as alocações de recursos atuais e os custos associados.
</Tip>

O armazenamento de objetos representa uma arquitetura de armazenamento em nuvem altamente escalável, durável e econômica oferecida pelos principais provedores de serviços em nuvem. Em ambientes de sandbox, o armazenamento de objetos pode ser acessado por meio de duas metodologias principais: interação programática direta via SDKs de provedores de nuvem ou utilitários CLI, ou por meio de implementações FUSE (Filesystem in Userspace) que apresentam buckets de armazenamento de objetos como montagens de sistema de arquivos padrão compatíveis com POSIX.

<Tip>
  [FUSE (Filesystem in Userspace)](https://www.kernel.org/doc/html/next/filesystems/fuse.html) é um módulo de kernel e uma biblioteca em espaço de usuário que permite a implementação de sistemas de arquivos totalmente funcionais em aplicações em espaço de usuário. Esse framework fornece uma camada de abstração que apresenta serviços remotos de armazenamento em nuvem como hierarquias padrão de sistema de arquivos, permitindo operações transparentes com arquivos por meio de interfaces POSIX convencionais.
</Tip>

Esta documentação fornece orientações abrangentes para integrar buckets de armazenamento de objetos dos principais provedores de serviços em nuvem a ambientes de sandbox por meio de técnicas de montagem de sistema de arquivos.

<Warning>
  Montagens de armazenamento de objetos baseadas em FUSE introduzem uma sobrecarga significativa de desempenho de I/O devido à latência de rede e às camadas de tradução de protocolo. Aplicações com requisitos rigorosos de desempenho devem evitar essa abordagem. Além disso, operações de sistema de arquivos FUSE não têm garantias de atomicidade inerentes às APIs nativas de armazenamento de objetos, criando possíveis condições de corrida em que operações locais de sistema de arquivos podem ser bem-sucedidas enquanto as operações remotas correspondentes falham, resultando em inconsistência de dados.

  Essa abordagem de montagem é ideal para cargas de trabalho com predominância de leitura, operações de escrita pouco frequentes e restrições de desempenho flexíveis. Para aplicações críticas em termos de desempenho ou padrões de escrita frequentes, recomenda-se fortemente a integração direta usando SDKs de provedores de nuvem ou APIs REST nativas.
</Warning>

<SandboxConfigHint />

## Amazon S3

Buckets do Amazon S3 podem ser montados como sistemas de arquivos compatíveis com POSIX usando [s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse), uma implementação de sistema de arquivos baseada em FUSE que fornece acesso a buckets S3 por meio de operações padrão de arquivos.

O pacote s3fs-fuse pode ser integrado durante a criação do [sandbox template](/docs/pt-BR/guides/sandbox-template-quickstart) por meio da incorporação de comandos de instalação no `novita.Dockerfile`, ou instalado dinamicamente em instâncias de sandbox ativas para requisitos ad hoc.

O seguinte `novita.Dockerfile` demonstra a integração do s3fs-fuse durante a construção do template:

<CodeGroup>
  ```dockerfile novita.Dockerfile icon="docker" theme={"system"}
  # Compatible with Debian-based distributions
  FROM ubuntu:latest

  # Critical: s3fs versions below 1.93 contain known mounting issues. Ensure version compatibility.
  RUN DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y s3fs
  ```
</CodeGroup>

A implementação a seguir demonstra a montagem programática de um bucket S3 em ambientes de sandbox usando s3fs-fuse:

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox'

  const TEMPLATE_ID = process.env.NOVITA_TEMPLATE_ID
  const AWS_ACCESS_KEY_ID = process.env.AWS_ACCESS_KEY_ID
  const AWS_SECRET_ACCESS_KEY = process.env.AWS_SECRET_ACCESS_KEY
  const AWS_BUCKET_NAME = process.env.AWS_BUCKET_NAME
  const AWS_REGION = process.env.AWS_REGION
  if (!TEMPLATE_ID || !AWS_ACCESS_KEY_ID || !AWS_SECRET_ACCESS_KEY || !AWS_BUCKET_NAME || !AWS_REGION) {
      throw new Error('Required environment variables not configured: NOVITA_TEMPLATE_ID, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_BUCKET_NAME, AWS_REGION')
  }

  const MOUNT_DIRECTORY = "/mnt/s3-bucket"

  const sandbox = await Sandbox.create(TEMPLATE_ID)

  // Initialize mount point directory structure
  await sandbox.files.makeDir(MOUNT_DIRECTORY)

  // Configure s3fs credentials using standard credential file location
  // s3fs-fuse reads AWS credentials from /root/.passwd-s3fs by default
  await sandbox.files.write('/root/.passwd-s3fs', `${AWS_ACCESS_KEY_ID}:${AWS_SECRET_ACCESS_KEY}`)

  // Enforce secure credential file permissions (owner read-only)
  await sandbox.commands.run('sudo chmod 600 /root/.passwd-s3fs')

  // Execute S3 bucket mount operation with optimized parameters
  // Configuration parameters:
  // - allow_other: Enable cross-user filesystem access
  // - endpoint: Specify the AWS region endpoint for your bucket
  // Reference: https://manpages.ubuntu.com/manpages/noble/en/man1/s3fs.1.html
  const mountOptions = `allow_other,endpoint=${AWS_REGION}`
  await sandbox.commands.run(`sudo s3fs ${AWS_BUCKET_NAME} ${MOUNT_DIRECTORY} -o ${mountOptions}`)

  // Validate mount functionality with write operation
  await sandbox.files.write(`${MOUNT_DIRECTORY}/test-file.txt`, 'test-file-content')

  // Verify mount integrity through read operation
  const content = await sandbox.files.read(`${MOUNT_DIRECTORY}/test-file.txt`)
  console.log(content)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  import os
  from novita_sandbox.core import Sandbox

  TEMPLATE_ID = os.environ.get("NOVITA_TEMPLATE_ID")
  AWS_ACCESS_KEY_ID = os.environ.get("AWS_ACCESS_KEY_ID")
  AWS_SECRET_ACCESS_KEY = os.environ.get("AWS_SECRET_ACCESS_KEY")
  AWS_BUCKET_NAME = os.environ.get("AWS_BUCKET_NAME")
  AWS_REGION = os.environ.get("AWS_REGION")
  if not TEMPLATE_ID or not AWS_ACCESS_KEY_ID or not AWS_SECRET_ACCESS_KEY or not AWS_BUCKET_NAME or not AWS_REGION:
      raise ValueError("Required environment variables not configured: NOVITA_TEMPLATE_ID, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_BUCKET_NAME, AWS_REGION")

  MOUNT_DIRECTORY = "/mnt/s3-bucket"

  sandbox = Sandbox.create(TEMPLATE_ID)

  # Initialize mount point directory structure
  sandbox.files.make_dir(MOUNT_DIRECTORY)

  # Configure s3fs credentials using standard credential file location
  # s3fs-fuse reads AWS credentials from /root/.passwd-s3fs by default
  # Custom credential paths require explicit specification via -o passwd_file parameter
  sandbox.files.write("/root/.passwd-s3fs", f"{AWS_ACCESS_KEY_ID}:{AWS_SECRET_ACCESS_KEY}")

  # Enforce secure credential file permissions (owner read-only)
  sandbox.commands.run("sudo chmod 600 /root/.passwd-s3fs")

  # Execute S3 bucket mount operation with optimized parameters
  # Configuration parameters:
  # - allow_other: Enable cross-user filesystem access
  # - endpoint: Specify the AWS region endpoint for your bucket
  # Reference: https://manpages.ubuntu.com/manpages/noble/en/man1/s3fs.1.html
  mount_options = f"allow_other,endpoint={AWS_REGION}"
  sandbox.commands.run(f"sudo s3fs {AWS_BUCKET_NAME} {MOUNT_DIRECTORY} -o {mount_options}")

  # Validate mount functionality with write operation
  write_result = sandbox.files.write(f"{MOUNT_DIRECTORY}/test-file.txt", "test-file-content")

  # Verify mount integrity through read operation
  content = sandbox.files.read(f"{MOUNT_DIRECTORY}/test-file.txt")
  print("File content:", content)

  sandbox.kill()
  ```
</CodeGroup>