Issue on docs: Title: VastAI.create_instance docs reference ssh=True/direct=True kwargs, but only create_template actually handles them

[saintbarber]

Path: /sdk/python/reference/create-instance

Environment

• vastai 1.0.13
• Python 3.14

Summary

The published docs for the Python SDK's create_instance (docs.vast.ai/sdk/python/reference/create-instance) suggest that ssh=True and direct=True can be passed as kwargs. In vastai==1.0.13 they're not handled by create_instance, they only get translated to the API's runtype field on create_template. Calling create_instance(..., ssh=True, direct=True) therefore does nothing useful (the kwargs are forwarded to instances.create_instance, which has no ssh/direct parameter).

Issue

The docs imply that create_instance accepts ssh=True, direct=True to provision an instance with a direct SSH port; without needing a template_hash.

What the SDK actually does:

vastai/sdk.py line 73

def create_instance(self, id: int, image: Optional[str] = None, disk: float = 10, **kwargs) -> dict:
        """Create a new instance from a contract offer ID."""
        return instances.create_instance(self.client, id, image=image, disk=disk, **kwargs)

The lower-level instances.create_instance has a fixed parameter list (no ssh, no direct), so the kwargs are either ignored or raise TypeError depending on what's passed.

vastai/api/instances.py line 71

def create_instance(client: VastClient, id, image=None, disk=10, env=None, price=None,
                    label=None, extra=None, onstart_cmd=None, login=None,
                    python_utf8=False, lang_utf8=False, jupyter_lab=False,
                    jupyter_dir=None, force=False, cancel_unavail=False,
                    template_hash=None, user=None, runtype=None, args=None,
                    volume_info=None) -> dict:

By contrast, create_template does translate the friendly kwargs:

vastai/sdk.py line 796

def create_template(self, **kwargs) -> dict:
        """Create a new template.

        Accepts user-friendly kwargs (jupyter, ssh, direct, login, etc.)
        and translates them to the API parameters.
        """
        jupyter = kwargs.pop("jupyter", False)
        ssh = kwargs.pop("ssh", False)
        direct = kwargs.pop("direct", False)
        login = kwargs.pop("login", None)
        hide_readme = kwargs.pop("hide_readme", False)
        public = kwargs.pop("public", False)
        jupyter_lab = kwargs.pop("jupyter_lab", False)
        # Remove kwargs not accepted by offers.create_template
        kwargs.pop("search_params", None)
        kwargs.pop("no_default", None)

        jup_direct = jupyter and direct
        ssh_direct = ssh and direct
        use_ssh = ssh or jupyter
        runtype = "jupyter" if jupyter else ("ssh" if ssh else "args")

And the CLI does the same translation for --ssh/--direct in get_runtype, feeding the resulting magic string into runtype on the instance-create request:

vastai/cli/commands/instances.py line 101

  elif args.ssh:
      runtype = 'ssh_direc ssh_proxy' if args.direct else 'ssh_proxy'

So the API path exists and the translation logic exists, it just isn't applied at the SDK's create_instance boundary.

The workaround I found is to simply provide the create_instance method the runtype parameter as it would with the CLI like so:

my own code

result = self.vast.create_instance(
            id=id,
            label=label,
            image=self.create_settings.get("image"),
            runtype="ssh_direc ssh_proxy",
            # direct=True,
            # ssh=True,
            disk=self.create_settings.get("disk", _DEFAULT_DISK),  # GB
        )

Reproduce Issue

from vastai import VastAI
v = VastAI(api_key="...")
v.create_instance(id=<offer_id>, image="vastai/base-image", ssh=True, direct=True)
# Does not produce an SSH-enabled instance; the ssh/direct kwargs are not
# translated. A template_hash or an explicit runtype="ssh_direc ssh_proxy"
# is required to actually get SSH+direct.